os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Partially convert the pr-guidelines article to the bugzilla world. This

Browse source 
is intentionally incomplete as the bugzilla states and categories are
not yet firm, and requires more precise wordsmihing.
This commit is contained in:
Eitan Adler 2014-06-29 07:40:16 +00:00
parent 13ba1d0039
commit 079b331ee0
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=45145
1 changed files with 33 additions and 164 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

197
en_US.ISO8859-1/articles/pr-guidelines/article.xml
View file

@ -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">
@ -192,19 +187,6 @@
</glossdef>
</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>
@ -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>
spammers found them.</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>
<para>Whenever you close one of these PRs, please do the
following:</para>
<itemizedlist>
<listitem>
<para>Set Category to <literal>junk</literal>.</para>
<para>Set the component to <literal>junk</literal> (under
<literal>Supporting Services</literal>.</para>
</listitem>
<listitem>
<para>Set Confidential to <literal>no</literal>.</para>
<para>Set Responsible to <literal>nobody@FreeBSD.org</literal>.</para>
</listitem>
<listitem>
<para>Set Responsible to <literal>gnats-admin</literal>.</para>
</listitem>
<listitem>
<para>Set State to <literal>closed</literal>.</para>
<para>Set State to <literal>Issue Resolved</literal>.</para>
</listitem>
</itemizedlist>