Date: Sun, 9 Jun 2002 01:18:29 -0400 (EDT) From: Chris Pepper <pepper@rockefeller.edu> To: FreeBSD-gnats-submit@FreeBSD.org Subject: docs/39055: PR Handling Guidelines: clean up typos, capitalize GNATS, and several rewordings to improve clarity. Message-ID: <200206090518.g595IT739115@guest.reppep.com>
next in thread | raw e-mail | index | archive | help
>Number: 39055 >Category: docs >Synopsis: PR Handling Guidelines: clean up typos, capitalize GNATS, and several rewordings to improve clarity. >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: doc-bug >Submitter-Id: current-users >Arrival-Date: Sat Jun 08 22:20:01 PDT 2002 >Closed-Date: >Last-Modified: >Originator: Chris Pepper >Release: FreeBSD 4.6-RC i386 >Organization: >Environment: System: FreeBSD guest.reppep.com 4.6-RC FreeBSD 4.6-RC #0: Fri Jun 7 21:51:10 EDT 2002 root@guest.reppep.com:/usr/obj/usr/src/sys/GENERIC i386 >Description: GNATS should be capitalized, per <http://www.fsf.org/software/gnats/gnats.html>. Changed a few typos, and reworded a bunch of sentences for clarity. Changed 'originator' to Reporter. Mentioned that PRs generally originate with the send-pr command or web form. Note: I don't know how to read or fix "If the problem contained within cannot be solved, or has occurred again, it is necessary to re-open the PR." >How-To-Repeat: View http://www.freebsd.org/doc/en/articles/pr-guidelines/article.html >Fix: Patch follows. --- article.sgml.patch begins here --- Index: article.sgml =================================================================== RCS file: /home/ncvs/doc/en_US.ISO8859-1/articles/pr-guidelines/article.sgml,v retrieving revision 1.5 diff -u -r1.5 article.sgml --- article.sgml 2002/05/24 19:30:51 1.5 +++ article.sgml 2002/06/09 05:08:54 @@ -41,17 +41,17 @@ <section> <title>Introduction</title> - <para>Gnats is a defect management (bug reporting) system used by + <para>GNATS is a defect management (bug reporting) system used by the FreeBSD Project. As accurate tracking of outstanding - software defects is important to the quality process, the - correct use of Gnats is essential to the forward progress of the + software defects is important to FreeBSD's quality, the + correct use of GNATS is essential to the forward progress of the Project.</para> - <para>Access to Gnats is provided to FreeBSD developers as well as + <para>Access to GNATS is available to FreeBSD developers, as well as to the wider community. In order to maintain consistency within - the database and provide a uniform user experience, guidelines + 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 + such as presenting followup, handling close requests, and so forth.</para> </section> @@ -60,14 +60,14 @@ <itemizedlist> <listitem> - <para>The originator submits a PR and receives a confirmation - message.</para> + <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>; </listitem> <listitem> <para>Joe Random Committer takes interest in the PR and assigns it to himself, or Jane Random BugBuster decides that - Joe is the best suited to handle it and assigns it to + Joe is best suited to handle it and assigns it to him.</para> </listitem> @@ -112,7 +112,7 @@ <note> <para>Many PRs are submitted with very little information about the problem, and some are either very complex to solve, or - just scratch the surface of a big problem; in these cases, it + just scratch the surface of a larger problem; in these cases, it is very important to obtain all the necessary information needed to solve the problem. If the problem contained within cannot be solved, or has occurred again, it is necessary to @@ -124,23 +124,23 @@ 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 / not installed.</para> + disabled or not installed.</para> </note> </section> <section> <title>Problem Report State</title> - <para>It is important to update the state of a PR when some + <para>It is important to update the state of a PR when certain actions are taken. The state should accurately reflect the current state of work on the PR.</para> <example> - <title>A small example on when to change a state</title> + <title>A small example on when to change PR state</title> <para>When a PR has been worked on and the developer(s) responsible feel comfortable about the fix, they will submit a - followup to the PR and change the state to + followup to the PR and change its state to <quote>feedback</quote>. At this point, the originator should evaluate the fix in their context and respond indicating whether the defect has indeed been remedied.</para> @@ -178,8 +178,8 @@ <glossentry> <glossterm>patched</glossterm> <glossdef> - <para>A patch has been committed, but some issues (MFC, or - maybe confirmation from originator) are still open.</para> + <para>A patch has been committed, but something (MFC, or + maybe confirmation from originator) is still pending.</para> </glossdef> </glossentry> @@ -190,9 +190,9 @@ information or resources. This is a prime candidate for somebody who is looking for a project to take on. If the problem cannot be solved at all, it will be closed, rather - than suspended. The documentation project use + than suspended. The documentation project uses <quote>suspended</quote> for <quote>wish-list</quote> - items that entail a significant amount of work that no one + items that entail a significant amount of work which no one currently has time for.</para> </glossdef> </glossentry> @@ -209,9 +209,8 @@ <note> <para>The <quote>patched</quote> state is directly related to - feedback, in that you may go directly change to this state if - the originator cannot test the patch, given that it - works.</para> + feedback, so you may go directly to <quote>closed</quote> state if + the originator cannot test the patch, and it works in your own testing.</para> </note> </section> @@ -230,7 +229,7 @@ assignee. If you have comments, submit a followup. If for some reason you think the PR should change state or be reassigned, send a message to the assignee. If the assignee - does not respond within two weeks, unassign the PR and do as + does not respond within two weeks, unassign or reassign the PR and do as you please.</para> </section> @@ -241,22 +240,21 @@ choose the one that contains the largest amount of useful information and close the others, stating clearly the number of the superseding PR. If several PRs contain non-overlapping - useful information, submit whatever is missing from the one - you keep open in a followup, with references to the PRs you - close.</para> + useful information, submit all the missing information to one + in a followup, including references to the others; then close the other PRs (which are now completely superseded).</para> </section> <section> <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:</para> + more than six months. Apply the following procedure to deal with stale PRs:</para> <itemizedlist> <listitem> <para>If the PR contains sufficient detail, try to reproduce the problem in <literal>-CURRENT</literal> and - <literal>-STABLE</literal>. if you succeed, submit a + <literal>-STABLE</literal>. If you succeed, submit a followup detailing your findings and try to find someone to assign it to. Set the state to <quote>analyzed</quote> if appropriate.</para> @@ -281,18 +279,18 @@ <listitem> <para>If the PR describes an error which you know has been corrected in <literal>-CURRENT</literal>, but not in - <literal>-STABLE</literal>, try to find out if the person - who corrected is planning to MFC it, or try to find + <literal>-STABLE</literal>, try to find out when the person + who corrected it is planning to MFC it, or try to find someone else (maybe yourself?) to do it. Set the state to <quote>feedback</quote> and assign it to whomever will do the MFC.</para> </listitem> <listitem> - <para>In all other cases, ask the originator to confirm if + <para>In other cases, ask the originator to confirm if the problem still exists in newer versions. If the originator does not reply within a month, close the PR - with the mention <quote>Feedback timeout</quote>.</para> + with the notation <quote>Feedback timeout</quote>.</para> </listitem> </itemizedlist> </section> --- article.sgml.patch ends here --- >Release-Note: >Audit-Trail: >Unformatted: To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200206090518.g595IT739115>