svn commit: r45145 - head/en_US.ISO8859-1/articles/pr-guidelines
Eitan Adler
eadler at FreeBSD.org
Sun Jun 29 07:40:16 UTC 2014
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: </literal></quote> part when you
- reply to the original mail message of a PR. The
- <quote><literal>category/number: </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 > 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 at 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 at 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>
More information about the svn-doc-head
mailing list