Skip site navigation (1)Skip section navigation (2)
Date:      Sun, 29 Jun 2014 07:40:16 +0000 (UTC)
From:      Eitan Adler <eadler@FreeBSD.org>
To:        doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org
Subject:   svn commit: r45145 - head/en_US.ISO8859-1/articles/pr-guidelines
Message-ID:  <201406290740.s5T7eGRG064519@svn.freebsd.org>

next in thread | raw e-mail | index | archive | help
Author: eadler
Date: Sun Jun 29 07:40:16 2014
New Revision: 45145
URL: http://svnweb.freebsd.org/changeset/doc/45145

Log:
  Partially convert the pr-guidelines article to the bugzilla world.  This
  is intentionally incomplete as the bugzilla states and categories are
  not yet firm, and requires more precise wordsmihing.

Modified:
  head/en_US.ISO8859-1/articles/pr-guidelines/article.xml

Modified: head/en_US.ISO8859-1/articles/pr-guidelines/article.xml
==============================================================================
--- head/en_US.ISO8859-1/articles/pr-guidelines/article.xml	Sun Jun 29 07:40:14 2014	(r45144)
+++ head/en_US.ISO8859-1/articles/pr-guidelines/article.xml	Sun Jun 29 07:40:16 2014	(r45145)
@@ -36,14 +36,14 @@
   <section xml:id="intro">
     <title>Introduction</title>
 
-    <para>GNATS is a defect management (bug reporting) system used by
-      the FreeBSD Project.  As accurate tracking of outstanding
+    <para>Bugzilla is an issue management system used by
+      the &os; 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>
+      correct use of the software 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
+    <para>Access to Bugzilla is available to the entire &os;
+      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
@@ -55,30 +55,37 @@
 
     <itemizedlist>
       <listitem>
-	<para>The Reporter submits a PR with &man.send-pr.1; and
-	  receives a confirmation message.</para>
+	<para>The Reporter submits a bug report on the website.  The
+	bug is in the <literal>Needs Triage</literal> state.</para>
+      </listitem>
+
+      <listitem>
+	<para>Jane Random BugBuster confirms that the bug report has
+	  sufficient information to be reproducible.  If not, she goes
+	  back and forth with the reporter to obtain the needed
+	  information.  At this point the bug is set to the
+	  <literal>Open</literal> state.</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>
+	  him.  The bug should be set to the <literal>In
+	  Discussion</literal> state.</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>
+	  cause of the problem.</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>
+	  state to <literal>Patch Ready</literal>.</para>
       </listitem>
 
       <listitem>
@@ -89,19 +96,15 @@
 	  <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>
+	  appropriate, start an MFC countdown.  The bug is set to the
+	  <literal>Needs MFC</literal> state.</para>
       </listitem>
 
       <listitem>
 	<para>If the patch does not need MFCing, Joe then closes the
-	  PR.</para>
+	  PR as <literal>Issue Resolved</literal>.</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>
@@ -113,14 +116,6 @@
 	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 xml:id="pr-states">
@@ -193,19 +188,6 @@
       </glossentry>
 
       <glossentry>
-	<glossterm>repocopy (obsolete)</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>
-
-	  <para>Given that all repositories now use Subversion, there is
-	    no need for this state anymore.  Subversion has native
-	    support for copying and moving files.</para>
-	</glossdef>
-      </glossentry>
-
-      <glossentry>
 	<glossterm>closed</glossterm>
 	<glossdef>
 	  <para>A problem report is closed when any changes have been
@@ -902,147 +884,34 @@
 	</listitem>
       </itemizedlist>
 
-      <section xml: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 xml: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 xml: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>
+	<title>Non-Bug PRs</title>
 
 	<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
+	  PR, informing the submitter in a comment 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
+	<para>The email addresses that Bugzilla 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>
+	  spammers found them.</para>
 
-	<itemizedlist>
-	  <listitem>
-	    <para>Set Category to <literal>junk</literal>.</para>
-	  </listitem>
+	<para>Whenever you close one of these PRs, please do the
+	  following:</para>
 
+	<itemizedlist>
 	  <listitem>
-	    <para>Set Confidential to <literal>no</literal>.</para>
+	    <para>Set the component to <literal>junk</literal> (under
+		<literal>Supporting Services</literal>.</para>
 	  </listitem>
 
 	  <listitem>
-	    <para>Set Responsible to <literal>gnats-admin</literal>.</para>
+	    <para>Set Responsible to <literal>nobody@FreeBSD.org</literal>.</para>
 	  </listitem>
 
 	  <listitem>
-	    <para>Set State to <literal>closed</literal>.</para>
+	    <para>Set State to <literal>Issue Resolved</literal>.</para>
 	  </listitem>
 	</itemizedlist>
 



Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201406290740.s5T7eGRG064519>