aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/articles/pr-guidelines/article.sgml
blob: aa822b7c58bd81b893f75dc243a4aa15aebabed1 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
<!--
	Problem Report Handling Guidelines
	The FreeBSD Project - http://www.FreeBSD.org
-->

<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN">
%articles.ent;
<!ENTITY man.edit-pr.1 "<citerefentry/<refentrytitle/edit-pr/<manvolnum/1//">
<!ENTITY man.query-pr.1 "<citerefentry/<refentrytitle/query-pr/<manvolnum/1//">
]>

<article>
  <!-- :START of Article Metadata -->
  <articleinfo>
    <title>Problem Report Handling Guidelines</title>

    <pubdate>$FreeBSD$</pubdate>

    <legalnotice id="trademarks" role="trademarks">
      &tm-attrib.freebsd;
      &tm-attrib.opengroup;
      &tm-attrib.general;
    </legalnotice>

    <abstract>
      <para>These guidelines describe recommended handling practices
	for FreeBSD Problem Reports (PRs).  Whilst developed for the
	FreeBSD PR Database Maintenance Team
	<email>freebsd-bugbusters@FreeBSD.org</email>, these
	guidelines should be followed by anyone working with FreeBSD
	PRs.</para>
    </abstract>

    <authorgroup>
      <author>
	<firstname>Dag-Erling</firstname>
	<surname>Sm&oslash;rgrav</surname>
      </author>

      <author>
	<firstname>Hiten</firstname>
	<surname>Pandya</surname>
      </author>
    </authorgroup>
  </articleinfo>
  <!-- :END of Article Metadata-->

  <section id="intro">
    <title>Introduction</title>

    <para>GNATS is a defect management (bug reporting) system used by
      the FreeBSD Project.  As accurate tracking of outstanding
      software defects is important to FreeBSD's quality, the
      correct use of GNATS is essential to the forward progress of the
      Project.</para>

    <para>Access to GNATS is available to FreeBSD developers, as well as
      to the wider community.  In order to maintain consistency within
      the database and provide a consistent user experience, guidelines
      have been established covering common aspects of bug management
      such as presenting followup, handling close requests, and so
      forth.</para>
  </section>

  <section id="pr-lifecycle">
    <title>Problem Report Life-cycle</title>

    <itemizedlist>
      <listitem>
	<para>The Reporter submits a PR with &man.send-pr.1; and
	  receives a confirmation message.</para>
      </listitem>

      <listitem>
	<para>Joe Random Committer takes interest in the PR and
	  assigns it to himself, or Jane Random BugBuster decides that
	  Joe is best suited to handle it and assigns it to
	  him.</para>
      </listitem>

      <listitem>
	<para>Joe has a brief exchange with the originator (making
	  sure it all goes into the audit trail) and determines the
	  cause of the problem.  He then makes sure the cause is
	  documented in the audit trail, and sets the PRs state to
	  <quote>analyzed</quote>.</para>
      </listitem>

      <listitem>
	<para>Joe pulls an all-nighter and whips up a patch that he
	  thinks fixes the problem, and submits it in a follow-up,
	  asking the originator to test it.  He then sets the PRs
	  state to <quote>feedback</quote>.</para>
      </listitem>

      <listitem>
	<para>A couple of iterations later, both Joe and the
	  originator are satisfied with the patch, and Joe commits it
	  to <literal>-CURRENT</literal> (or directly to
	  <literal>-STABLE</literal> if the problem does not exist in
	  <literal>-CURRENT</literal>), making sure to reference the
	  Problem Report in his commit log (and credit the originator
	  if he submitted all or part of the patch) and, if
	  appropriate, start an MFC countdown.</para>
      </listitem>

      <listitem>
	<para>If the patch does not need MFCing, Joe then closes the
	  PR.</para>
      </listitem>

      <listitem>
	<para>If the patch needs MFCing, Joe leaves the Problem Report
	  in <quote>patched</quote> state until the patch has been
	  MFCed, then closes it.</para>
      </listitem>
    </itemizedlist>

    <note>
      <para>Many PRs are submitted with very little information about
	the problem, and some are either very complex to solve, or
	just scratch the surface of a larger problem; in these cases, it
	is very important to obtain all the necessary information
	needed to solve the problem.  If the problem contained within
	cannot be solved, or has occurred again, it is necessary to
	re-open the PR.</para>
    </note>
    <note>
      <para>The <quote>email address</quote> used on the PR might not
	be able to receive mail.  In this case, followup to the PR as
	usual and ask the originator (in the followup) to provide a
	working email address.  This is normally the case when
	&man.send-pr.1; is used from a system with the mail system
	disabled or not installed.</para>
    </note>
  </section>

  <section id="pr-states">
    <title>Problem Report State</title>

    <para>It is important to update the state of a PR when certain
      actions are taken.  The state should accurately reflect the
      current state of work on the PR.</para>

    <example>
      <title>A small example on when to change PR state</title>

      <para>When a PR has been worked on and the developer(s)
	responsible feel comfortable about the fix, they will submit a
	followup to the PR and change its state to
	<quote>feedback</quote>.  At this point, the originator should
	evaluate the fix in their context and respond indicating
	whether the defect has indeed been remedied.</para>
    </example>

    <para>A Problem Report may be in one of the following
      states:</para>

    <glosslist>
      <glossentry>
	<glossterm>open</glossterm>
	<glossdef>
	  <para>Initial state; the problem has been pointed out and it
	    needs reviewing.</para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm>analyzed</glossterm>
	<glossdef>
	  <para>The problem has been reviewed and a
	solution is being sought.</para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm>feedback</glossterm>
	<glossdef>
	  <para>Further work requires additional information from the
	    originator or the community; possibly information
	    regarding the proposed solution.</para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm>patched</glossterm>
	<glossdef>
	  <para>A patch has been committed, but something (MFC, or
	    maybe confirmation from originator) is still pending.</para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm>suspended</glossterm>
	<glossdef>
	  <para>The problem is not being worked on, due to lack of
	    information or resources.  This is a prime candidate for
	    somebody who is looking for a project to take on.  If the
	    problem cannot be solved at all, it will be closed, rather
	    than suspended.  The documentation project uses
	    <quote>suspended</quote> for <quote>wish-list</quote>
	    items that entail a significant amount of work which no one
	    currently has time for.</para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm>repocopy</glossterm>
	<glossdef>
	  <para>The resolution of the problem report is dependent on a
	    repository copy, or repocopy, operation within the CVS
	    repository which is awaiting completion.</para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm>closed</glossterm>
	<glossdef>
	  <para>A problem report is closed when any changes have been
	    integrated, documented, and tested, or when fixing the
	    problem is abandoned.</para>
	</glossdef>
      </glossentry>
    </glosslist>

    <note>
      <para>The <quote>patched</quote> state is directly related to
	feedback, so you may go directly to <quote>closed</quote> state if
	the originator cannot test the patch, and it works in your own testing.</para>
    </note>
  </section>

  <section id="pr-types">
    <title>Types of Problem Reports</title>

    <para>While handling problem reports, either as a developer who has
      direct access to the GNATS database or as a contributor who
      browses the database and submits followups with patches, comments,
      suggestions or change requests, you will come across several
      different types of PRs.</para>

    <itemizedlist>
      <listitem>
	<para><link linkend="pr-unassigned">PRs not yet assigned to anyone.</link></para>
      </listitem>
      <listitem>
	<para><link linkend="pr-assigned">PRs already assigned to someone.</link></para>
      </listitem>
      <listitem>
	<para><link linkend="pr-dups">Duplicates of existing PRs.</link></para>
      </listitem>
      <listitem>
	<para><link linkend="pr-stale">Stale PRs</link></para>
      </listitem>
      <listitem>
	<para><link linkend="pr-misfiled">Misfiled PRs</link></para>
      </listitem>
    </itemizedlist>

    <para>The following sections describe what each different type of
      PRs is used for, when a PR belongs to one of these types, and what
      treatment each different type receives.</para>

    <section id="pr-unassigned">
      <title>Unassigned PRs</title>

      <para>When PRs arrive, they are initially assigned to a generic
	(placeholder) assignee.  These are always prepended with
	<literal>freebsd-</literal>.  The exact value for this default
	depends on the category; in most cases, it corresponds to a
	specific &os; mailing list.  Here is the current list, with
	the most common ones listed first:</para>

      <table id=default-assignees-common>
	<title>Default Assignees &mdash; most common</title>
	<tgroup cols="3">
	  <thead>
	    <row>
	      <entry>Type</entry>
	      <entry>Categories</entry>
	      <entry>Default Assignee</entry>
	    </row>
	  </thead>

	  <tbody>
	    <row>
	      <entry>base system</entry>
	      <entry>bin, conf, gnu, kern, misc</entry>
	      <entry>freebsd-bugs</entry>
	    </row>

	    <row>
	      <entry>architecture-specific</entry>
	      <entry>alpha, amd64, arm, i386, ia64, powerpc, sparc64</entry>
	      <entry>freebsd-<replaceable>arch</replaceable></entry>
	    </row>

	    <row>
	      <entry>ports collection</entry>
	      <entry>ports</entry>
	      <entry>freebsd-ports-bugs</entry>
	    </row>

	    <row>
	      <entry>documentation shipped with the system</entry>
	      <entry>docs</entry>
	      <entry>freebsd-doc</entry>
	    </row>

	    <row>
	      <entry>&os; web pages (not including docs)</entry>
	      <entry>www</entry>
	      <entry>freebsd-www</entry>
	    </row>
	  </tbody>
      </table>

      <table id=default-assignees-other>
	<title>Default Assignees &mdash; other</title>
	<tgroup cols="3">
	  <thead>
	    <row>
	      <entry>Type</entry>
	      <entry>Categories</entry>
	      <entry>Default Assignee</entry>
	    </row>
	  </thead>

	  <tbody>
	    <row>
	      <entry>advocacy efforts</entry>
	      <entry>advocacy</entry>
	      <entry>freebsd-advocacy</entry>
	    </row>

	    <row>
	      <entry>&man.jail.8; subsystem</entry>
	      <entry>jail</entry>
	      <entry>freebsd-jail</entry>
	    </row>

	    <row>
	      <entry>&java.virtual.machine; problems</entry>
	      <entry>java</entry>
	      <entry>freebsd-java</entry>
	    </row>

	    <row>
	      <entry>standards compliance</entry>
	      <entry>standards</entry>
	      <entry>freebsd-standards</entry>
	    </row>

	    <row>
	      <entry>threading libraries</entry>
	      <entry>threads</entry>
	      <entry>freebsd-threads</entry>
	    </row>

	    <row>
	      <entry>&man.usb.4; subsystem</entry>
	      <entry>usb</entry>
	      <entry>freebsd-usb</entry>
	    </row>
	  </tbody>
      </table>

      <para>Do not be surprised to find that the submitter of the
	PR has assigned it to the wrong category.  If you fix the
	category, do not forget to fix the assignment as well.
	(In particular, our submitters seem to have a hard time
	understanding that just because their problem manifested
	on an i386 system, that it might be generic to all of &os;,
	and thus be more appropriate for <literal>kern</literal>.
	The converse is also true, of course.)</para>

      <para>Certain PRs may be reassigned away from these generic
	assignees by anyone.  For assignees which are mailing lists,
	please use the long form when making the assignment (e.g.,
	<literal>freebsd-foo</literal> instead of <literal>foo</literal>);
	this will avoid duplicate emails sent to the mailing list.</para>

      <note>
	<para>Here is a sample list of such entities; it is probably
	  not complete.  In some cases, entries that have the short form are
	  <emphasis>aliases</emphasis>, not mailing lists.</para>
      </note>

      <table id=common-assignees-base>
	<title>Common Assignees &mdash; base system</title>
	<tgroup cols="3">
	  <thead>
	    <row>
	      <entry>Type</entry>
	      <entry>Suggested Category</entry>
	      <entry>Suggested Assignee</entry>
	    </row>
	  </thead>

	  <tbody>
	    <row>
	      <entry>problem specific to the &arm; architecture</entry>
	      <entry>kern</entry>
	      <entry>freebsd-arm</entry>
	    </row>

	    <row>
	      <entry>problem specific to the &mips; architecture</entry>
	      <entry>kern</entry>
	      <entry>freebsd-mips</entry>
	    </row>

	    <row>
	      <entry>problem specific to the &powerpc; architecture</entry>
	      <entry>kern</entry>
	      <entry>freebsd-ppc</entry>
	    </row>

	    <row>
	      <entry>problem with Advanced Configuration and Power
		Management (&man.acpi.4;)</entry>
	      <entry>kern</entry>
	      <entry>freebsd-acpi</entry>
	    </row>

	    <row>
	      <entry>problem with Asynchronous Transfer Mode (ATM)
		drivers</entry>
	      <entry>kern</entry>
	      <entry>freebsd-atm</entry>
	    </row>

	    <row>
	      <entry>problem with embedded or small-footprint &os;
		systems (e.g., NanoBSD/PicoBSD/FreeBSD-arm)</entry>
	      <entry>kern</entry>
	      <entry>freebsd-embedded</entry>
	    </row>

	    <row>
	      <entry>problem with &firewire; drivers</entry>
	      <entry>kern</entry>
	      <entry>freebsd-firewire</entry>
	    </row>

	    <row>
	      <entry>problem with the filesystem code</entry>
	      <entry>kern</entry>
	      <entry>freebsd-fs</entry>
	    </row>

	    <row>
	      <entry>problem with the &man.geom.4; subsystem</entry>
	      <entry>kern</entry>
	      <entry>freebsd-geom</entry>
	    </row>

	    <row>
	      <entry>problem with the &man.ipfw.4; subsystem</entry>
	      <entry>kern</entry>
	      <entry>freebsd-ipfw</entry>
	    </row>

	    <row>
	      <entry>problem with Integrated Services Digital Network
		(ISDN) drivers</entry>
	      <entry>kern</entry>
	      <entry>freebsd-isdn</entry>
	    </row>

	    <row>
	      <entry>problem with &linux; or SVR4 emulation</entry>
	      <entry>kern</entry>
	      <entry>freebsd-emulation</entry>
	    </row>

	    <row>
	      <entry>problem with the networking stack</entry>
	      <entry>kern</entry>
	      <entry>freebsd-net</entry>
	    </row>

	    <row>
	      <entry>problem with the &man.pf.4; subsystem</entry>
	      <entry>kern</entry>
	      <entry>freebsd-pf</entry>
	    </row>

	    <row>
	      <entry>problem with the &man.scsi.4; subsystem</entry>
	      <entry>kern</entry>
	      <entry>freebsd-scsi</entry>
	    </row>

	    <row>
	      <entry>problem with the &man.sound.4; subsystem</entry>
	      <entry>kern</entry>
	      <entry>freebsd-multimedia</entry>
	    </row>

	    <row>
	      <entry>problem with &man.sysinstall.8;</entry>
	      <entry>bin</entry>
	      <entry>freebsd-qa</entry>
	    </row>

	    <row>
	      <entry>problem with the system startup scripts
		(&man.rc.8;)</entry>
	      <entry>kern</entry>
	      <entry>freebsd-rc</entry>
	    </row>
	  </tbody>
      </table>

      <table id=common-assignees-ports>
	<title>Common Assignees &mdash; Ports Collection</title>
	<tgroup cols="3">
	  <thead>
	    <row>
	      <entry>Type</entry>
	      <entry>Suggested Category</entry>
	      <entry>Suggested Assignee</entry>
	    </row>
	  </thead>

	  <tbody>
	    <row>
	      <entry>problem with the ports framework
		(<emphasis>not</emphasis> with an individual port!)</entry>
	      <entry>ports</entry>
	      <entry>portmgr</entry>
	    </row>

	    <row>
	      <entry>port which is maintained by apache@FreeBSD.org</entry>
	      <entry>ports</entry>
	      <entry>apache</entry>
	    </row>

	    <row>
	      <entry>port which is maintained by eclipse@FreeBSD.org</entry>
	      <entry>ports</entry>
	      <entry>freebsd-eclipse</entry>
	    </row>

	    <row>
	      <entry>port which is maintained by gnome@FreeBSD.org</entry>
	      <entry>ports</entry>
	      <entry>gnome</entry>
	    </row>

	    <row>
	      <entry>port which is maintained by haskell@FreeBSD.org</entry>
	      <entry>ports</entry>
	      <entry>haskell</entry>
	    </row>

	    <row>
	      <entry>port which is maintained by java@FreeBSD.org</entry>
	      <entry>ports</entry>
	      <entry>freebsd-java</entry>
	    </row>

	    <row>
	      <entry>port which is maintained by kde@FreeBSD.org</entry>
	      <entry>ports</entry>
	      <entry>kde</entry>
	    </row>

	    <row>
	      <entry>port which is maintained by
		openoffice@FreeBSD.org</entry>
	      <entry>ports</entry>
	      <entry>freebsd-openoffice</entry>
	    </row>

	    <row>
	      <entry>port which is maintained by perl@FreeBSD.org</entry>
	      <entry>ports</entry>
	      <entry>perl</entry>
	    </row>

	    <row>
	      <entry>port which is maintained by python@FreeBSD.org</entry>
	      <entry>ports</entry>
	      <entry>freebsd-python</entry>
	    </row>

	    <row>
	      <entry>port which is maintained by x11@FreeBSD.org</entry>
	      <entry>ports</entry>
	      <entry>freebsd-x11</entry>
	    </row>
	  </tbody>
      </table>

      <para>Ports PRs which have a maintainer who is a ports committer
	may be reassigned by anyone (but note that not every &os;
	committer is necessarily a ports committer, so you cannot
	simply go by the email address alone.)
      </para>

      <para>For other PRs, please do not reassign them to individuals
	(other than yourself) unless you are certain that the assignee
	really wants to track the PR.  This will help to avoid the
	case where no one looks at fixing a particular problem
	because everyone assumes that the assignee is already working
	on it.</para>

    </section>

    <section id="pr-assigned">
      <title>Assigned PRs</title>

      <para>If a PR has the <literal>responsible</literal> field set
	to the username of a FreeBSD developer, it means that the PR
	has been handed over to that particular person for further
	work.</para>

      <para>Assigned PRs should not be touched by anyone but the
	assignee.  If you have comments, submit a followup.  If for
	some reason you think the PR should change state or be
	reassigned, send a message to the assignee.  If the assignee
	does not respond within two weeks, unassign the PR and do as
	you please.</para>
    </section>

    <section id="pr-dups">
      <title>Duplicate PRs</title>

      <para>If you find more than one PR that describe the same issue,
	choose the one that contains the largest amount of useful
	information and close the others, stating clearly the number
	of the superseding PR.  If several PRs contain non-overlapping
	useful information, submit all the missing information to one
	in a followup, including references to the others; then close
	the other PRs (which are now completely superseded).</para>
    </section>

    <section id="pr-stale">
      <title>Stale PRs</title>

      <para>A PR is considered stale if it has not been modified in more
	than six months.  Apply the following procedure to deal with
	stale PRs:</para>

      <itemizedlist>
	<listitem>
	  <para>If the PR contains sufficient detail, try to reproduce
	    the problem in <literal>-CURRENT</literal> and
	    <literal>-STABLE</literal>.  If you succeed, submit a
	    followup detailing your findings and try to find someone
	    to assign it to.  Set the state to <quote>analyzed</quote>
	    if appropriate.</para>
	</listitem>

	<listitem>
	  <para>If the PR describes an issue which you know is the
	    result of a usage error (incorrect configuration or
	    otherwise), submit a followup explaining what the
	    originator did wrong, then close the PR with the reason
	    <quote>User error</quote> or <quote>Configuration
	    error</quote>.</para>
	</listitem>

	<listitem>
	  <para>If the PR describes an error which you know has been
	    corrected in both <literal>-CURRENT</literal> and
	    <literal>-STABLE</literal>, close it with a message
	    stating when it was fixed in each branch.</para>
	</listitem>

	<listitem>
	  <para>If the PR describes an error which you know has been
	    corrected in <literal>-CURRENT</literal>, but not in
	    <literal>-STABLE</literal>, try to find out when the person
	    who corrected it is planning to MFC it, or try to find
	    someone else (maybe yourself?) to do it.  Set the state to
	    <quote>patched</quote> and assign it to whomever will do
	    the MFC.</para>
	</listitem>

	<listitem>
	  <para>In other cases, ask the originator to confirm if
	    the problem still exists in newer versions.  If the
	    originator does not reply within a month, close the PR
	    with the notation <quote>Feedback timeout</quote>.</para>
	</listitem>
      </itemizedlist>
    </section>

    <section id="pr-misfiled">
      <title>Misfiled PRs</title>

      <para>GNATS is picky about the format of a submitted bug report.
	This is why a lot of PRs end up being <quote>misfiled</quote> if
	the submitter forgets to fill in a field or puts the wrong sort of
	data in some of the PR fields.  This section aims to provide most
	of the necessary details for FreeBSD developers that can help them to
	close or refile these PRs.</para>

      <para>When GNATS cannot deduce what to do with a problem report
	that reaches the database, it sets the responsible of the PR to
	<literal>gnats-admin</literal> and files it under the
	<literal>pending</literal> category.  This is now a
	<quote>misfiled</quote> PR and will not appear in bug report
	listings, unless someone explicitly asks for a list of all the
	misfiled PRs.  If you have access to the FreeBSD cluster
	machines, you can use <command>query-pr</command> to view a
	listing of PRs that have been misfiled:</para>

      <screen>&prompt.user; <userinput>query-pr -x -q -r gnats-admin</userinput>
   52458 gnats-ad   open      serious   medium    Re: declaration clash f
   52510 gnats-ad   open      serious   medium    Re: lots of sockets in
   52557 gnats-ad   open      serious   medium
   52570 gnats-ad   open      serious   medium    Jigdo maintainer update</screen>

      <para>Commonly PRs like the ones shown above are misfiled for one
	of the following reasons:</para>

      <itemizedlist>
	<listitem>
	  <para>A followup to an existing PR, sent through email, has
	    the wrong format on its <literal>Subject:</literal>
	    header.</para>
	</listitem>

	<listitem>
	  <para>A submitter sent a Cc: to a mailing list and someone
	    followed up to that post instead of the email issued by
	    GNATS after processing.  The email to the list will not
	    have the category/PRnumber tracking tag.  (This is why we
	    discourage submitters from doing this exact thing.)</para>
	</listitem>

	<listitem>
	  <para>When completing the &man.send-pr.1; template, the submitter
	    forgot to set the category or class of the PR to a proper
	    value.</para>
	</listitem>

	<listitem>
	  <para>When completing the &man.send-pr.1; template, the submitter
	    set Confidential to <literal>yes</literal>.  (Since we allow
	    anyone to mirror GNATS via <application>cvsup</application>,
	    our PRs are public information.  Security alerts should
	    therefore not be sent via GNATS but instead via email to
	    the Security Team.)</para>
	</listitem>

	<listitem>
	  <para>It is not a real PR, but some random message sent to
	    <email>bug-followup@FreeBSD.org</email> or
	    <email>freebsd-gnats-submit@FreeBSD.org</email>.</para>
	</listitem>
      </itemizedlist>

      <section id="pr-misfiled-followups">
	<title>Followups misfiled as new PRs</title>

	<para>The first category of misfiled PRs, the one with the wrong
	  subject header, is actually the one that requires the greatest
	  amount of work from developers.  These are not real PRs,
	  describing separate problem reports.  When a reply is received
	  for an existing PR at one of the addresses that GNATS
	  <quote>listens</quote> to for incoming messages, the subject
	  of the reply should always be of the form:</para>

	<programlisting>Subject: Re: category/number: old synopsis text</programlisting>

	<para>Most mailers will add the
	  <quote><literal>Re:&nbsp;</literal></quote> part when you
	  reply to the original mail message of a PR.  The
	  <quote><literal>category/number:&nbsp;</literal></quote> part
	  is a GNATS-specific convention that you have to manually
	  insert to the subject of your followup reports.</para>

	<para>Any FreeBSD developer, who has direct access to the GNATS
	  database, can periodically check for PRs of this sort and move
	  interesting bits of the misfiled PR into the audit trail of
	  the original PR (by posting a proper followup to a bug report
	  to the address &a.bugfollowup;).  Then
	  the misfiled PR can be closed with a message similar
	  to:</para>

	<programlisting>Your problem report was misfiled.  Please use the format
"Subject: category/number: original text" when following
up to older, existing PRs.  I've added the relevant bits
from the body of this PR to kern/12345</programlisting>

	<para>Searching with <command>query-pr</command> for the
	  original PR, of which a misfiled followup is a reply, is as
	  easy as running:</para>

	<screen>&prompt.user; query-pr -q -y "some text"</screen>

	<para>After you locate the original PR and the misfiled
	  followups, use the <option>-F</option> option of
	  <command>query-pr</command> to save the full text of all the
	  relevant PRs in a &unix; mailbox file, i.e.:</para>

	<screen>&prompt.user; <userinput>query-pr -F 52458 52474 &gt; mbox</userinput></screen>

	<para>Now you can use any mail user agent to view all the PRs
	  you saved in <filename>mbox</filename>.  Copy the text of all
	  the misfiled PRs in a followup to the original PR and make
	  sure you include the proper <literal>Subject:</literal>
	  header.  Then close the misfiled PRs.  When you close the misfiled
	  PRs remember that the submitter receives a mail notification that
	  his PR changed state to <quote>closed</quote>.  Make sure you
	  provide enough details in the log about the reason of this state
	  change.  Typically something like the following is ok:</para>

	<programlisting>Followup to ports/45364 misfiled as a new PR.
This was misfiled because the subject did not have the format:

	Re: ports/45364: ...</programlisting>

	<para>This way the submitter of the misfiled PR will know what to
	  avoid the next time a followup to an existing PR is sent.</para>
      </section>

      <section id="pr-misfiled-format">
	<title>PRs misfiled because of missing fields</title>

	<para>The second type of misfiled PRs is usually the result of a
	  submitter forgetting to fill all the necessary fields when
	  writing the original PR.</para>

	<para>Missing or bogus <quote>category</quote> or
	  <quote>class</quote> fields can result in a misfiled report.
	  Developers can use &man.edit-pr.1; to change the category or
	  class of these misfiled PRs to a more appropriate value and
	  save the PR.</para>

	<para>Another common cause of misfiled PRs because of formatting
	  issues is quoting, changes or removal of the
	  <command>send-pr</command> template, either by the user who
	  edits the template or by mailers which do strange things to
	  plain text messages.  This does not happen a lot of the time,
	  but it can be fixed with <command>edit-pr</command> too; it
	  does require a bit of work from the developer who refiles the
	  PR, but it is relatively easy to do most of the time.</para>
      </section>

      <section id="pr-misfiled-notpr">
	<title>Misfiled PRs that are not really problem reports</title>

	<para>Sometimes a user wants to submit a report for a problem
	  and sends a simple email message to GNATS.  The GNATS scripts
	  will recognize bug reports that are formatted using the
	  &man.send-pr.1; template.  They cannot parse any sort of email
	  though.  This is why submissions of bug reports that are sent
	  to <email>freebsd-gnats-submit@FreeBSD.org</email> have to
	  follow the template of <command>send-pr</command>, but email
	  reports can be sent to &a.bugs;.</para>

	<para>Developers that come across PRs that look like they should have
	  been posted to &a.bugs.name; or some other list should close the
	  PR, informing the submitter in their state-change log why this
	  is not really a PR and where the message should be posted.</para>

	<para>The email addresses that GNATS listens to for incoming PRs
	  have been published as part of the FreeBSD documentation, have
	  been announced and listed on the web-site.  This means that
	  spammers found them.  Spam messages
	  that reach GNATS are promptly filed
	  under the <quote>pending</quote> category until someone looks
	  at them.  Closing one of these with &man.edit-pr.1; is very
	  annoying though, because GNATS replies to the submitter and
	  the sender's address of spam mail is never valid these days.
	  Bounces will come back for each PR that is closed.</para>

	<para>Currently, with the installation of some antispam filters
	  that check all submissions to the GNATS database, the amount
	  of spam that reaches the <quote>pending</quote> state is very
	  small.</para>

	<para>All developers who have access to the FreeBSD.org cluster
	  machines are encouraged to check for misfiled PRs and immediately
	  close those that are spam mail.  Whenever you close one of
	  these PRs, please do the following:</para>

	<itemizedlist>
	  <listitem>
	    <para>Set Category to <literal>junk</literal>.</para>
	  </listitem>

	  <listitem>
	    <para>Set Confidential to <literal>no</literal>.</para>
	  </listitem>

	  <listitem>
	    <para>Set Responsible to yourself (and not, e.g.,
	      <literal>freebsd-bugs</literal>, which merely
	      sends more mail).</para>
	  </listitem>

	  <listitem>
	    <para>Set State to <literal>closed</literal>.</para>
	  </listitem>
	</itemizedlist>

	<para>Junk PRs are not
	  backed up, so filing spam mail under this category makes it
	  obvious that we do not care to keep it around or waste disk
	  space for it.  If you merely close them without changing the
	  category, they remain both in the master database and in
	  any copies of the database mirrored through
	  <application>cvsup</application>.</para>
      </section>
    </section>
  </section>

  <section id="references">
    <title>Further Reading</title>

    <para>This is a list of resources relevant to the proper writing
      and processing of problem reports.  It is by no means complete.</para>

    <itemizedlist>
      <listitem>
	<para><ulink
	  url="&url.articles.problem-reports;/article.html">How to
	  Write FreeBSD Problem Reports</ulink>&mdash;guidelines
	  for PR originators.</para>
      </listitem>
    </itemizedlist>
  </section>
</article>