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: </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@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>