1 files changed, 223 insertions, 14 deletions

diff --git a/en_US.ISO8859-1/articles/pr-guidelines/article.sgml b/en_US.ISO8859-1/articles/pr-guidelines/article.sgml
index 766780e0fe..634c46d156 100644
--- a/en_US.ISO8859-1/articles/pr-guidelines/article.sgml
+++ b/en_US.ISO8859-1/articles/pr-guidelines/article.sgml
@@ -6,6 +6,10 @@
 <!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
 <!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
 %man;
+<!ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//EN">
+%mailing-lists;
+<!ENTITY man.edit-pr.1 "<citerefentry/<refentrytitle/edit-pr/<manvolnum/1//">
+<!ENTITY man.query-pr.1 "<citerefentry/<refentrytitle/query-pr/<manvolnum/1//">
 ]>
 
 <article>
@@ -38,7 +42,7 @@
   </articleinfo>
   <!-- :END of Article Metadata-->
 
-  <section>
+  <section id="intro">
     <title>Introduction</title>
 
     <para>GNATS is a defect management (bug reporting) system used by
@@ -55,15 +59,13 @@
       forth.</para>
   </section>
 
-  <section>
+  <section id="pr-lifecycle">
     <title>Problem Report Life-cycle</title>
 
     <itemizedlist>
       <listitem>
-	<para>The Reporter submits a PR and receives a confirmation
-	  message, most likely via &man.send-pr.1; or the Problem Report web form at
-	  <ulink url="http://www.FreeBSD.org/send-pr.html">
-	    http://www.FreeBSD.org/send-pr.html</ulink>.</para>
+	<para>The Reporter submits a PR with &man.send-pr.1; and
+	  receives a confirmation message.</para>
       </listitem>
 
       <listitem>
@@ -130,7 +132,7 @@
     </note>
   </section>
 
-  <section>
+  <section id="pr-states">
     <title>Problem Report State</title>
 
     <para>It is important to update the state of a PR when certain
@@ -216,10 +218,35 @@
     </note>
   </section>
 
-  <section>
+  <section id="pr-types">
     <title>Types of Problem Reports</title>
 
-    <section>
+    <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-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-assigned">
       <title>Assigned PRs</title>
 
       <para>If a PR has the <literal>responsible</literal> field set
@@ -235,7 +262,7 @@
 	you please.</para>
     </section>
 
-    <section>
+    <section id="pr-dups">
       <title>Duplicate PRs</title>
 
       <para>If you find more than one PR that describe the same issue,
@@ -247,11 +274,12 @@
 	the other PRs (which are now completely superseded).</para>
     </section>
 
-    <section>
+    <section id="pr-stale">
       <title>Stale PRs</title>
 
-      <para>A PR is considered stale if it hasn't been modified in
-	more than six months.  Apply the following procedure to deal with stale PRs:</para>
+      <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>
@@ -297,9 +325,190 @@
 	</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 a field or puts the wrong sort of
+	data some of the PR fields.  This section aims to provide most
+	of the necessary details for FreeBSD developers that can help
+	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 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 -q -r gnats-admin | grep -v closed</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>When filling 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>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 <email>bug-followup@freebsd.org</email>).  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 didn't 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 who forgot 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 who do strange things to
+	  plain text messages.  This doesn't 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's 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>Some times 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 send
+	  to <email>freebsd-gnats-submit@freebsd.org</email> have to
+	  follow the template of <command>send-pr</command> but email
+	  reports sent to &a.bugs;.</para>
+
+	<para>Developers that come across PRs that look like they should
+	  be 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.  Every day several messages with
+	  advertisements would reach GNATS which promptly files them all
+	  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 immediately
+	  close those that are spam mail.  Whenever you close one of
+	  these PRs it is also a good idea to set its category to
+	  <quote><literal>junk</literal></quote>.  Junk PRs are not
+	  backed up, so filing spam mail under this category makes it
+	  obvious that we do not care to keep around and waste disk
+	  space for it.</para>
+      </section>
+    </section>
   </section>
 
-  <section>
+  <section id="references">
     <title>Further Reading</title>
 
     <para>This is a list of resources relevant to the proper writing