diff --git a/en_US.ISO8859-1/articles/pr-guidelines/article.sgml b/en_US.ISO8859-1/articles/pr-guidelines/article.sgml index 766780e0fe..634c46d156 100644 --- a/en_US.ISO8859-1/articles/pr-guidelines/article.sgml +++ b/en_US.ISO8859-1/articles/pr-guidelines/article.sgml @@ -6,6 +6,10 @@ %man; + +%mailing-lists; + + ]>
@@ -38,7 +42,7 @@ -
+
Introduction GNATS is a defect management (bug reporting) system used by @@ -55,15 +59,13 @@ forth.
-
+
Problem Report Life-cycle - The Reporter submits a PR and receives a confirmation - message, most likely via &man.send-pr.1; or the Problem Report web form at - - http://www.FreeBSD.org/send-pr.html. + The Reporter submits a PR with &man.send-pr.1; and + receives a confirmation message. @@ -130,7 +132,7 @@
-
+
Problem Report State It is important to update the state of a PR when certain @@ -216,10 +218,35 @@
-
+
Types of Problem Reports -
+ While handling problem reports, either as a developer who has + direct access to the GNATS database or as a contributor who + browses the database and submits followups with patches, comments, + suggestions or change requests, you will come across several + different types of PRs. + + + + PRs already assigned to someone. + + + Duplicates of existing PRs. + + + Stale PRs + + + Misfiled PRs + + + + The following sections describe what each different type of + PRs is used for, when a PR belongs to one of these types, and what + treatment each different type receives. + +
Assigned PRs If a PR has the responsible field set @@ -235,7 +262,7 @@ you please.
-
+
Duplicate PRs If you find more than one PR that describe the same issue, @@ -247,11 +274,12 @@ the other PRs (which are now completely superseded).
-
+
Stale PRs - A PR is considered stale if it hasn't been modified in - more than six months. Apply the following procedure to deal with stale PRs: + A PR is considered stale if it has not been modified in more + than six months. Apply the following procedure to deal with + stale PRs: @@ -297,9 +325,190 @@
+ +
+ Misfiled PRs + + GNATS is picky about the format of a submitted bug report. + This is why a lot of PRs end up being misfiled if + the submitter forgets to fill a field or puts the wrong sort of + data some of the PR fields. This section aims to provide most + of the necessary details for FreeBSD developers that can help + close or refile these PRs. + + When GNATS cannot deduce what to do with a problem report + that reaches the database, it sets the responsible of the PR to + gnats-admin and files it under the + pending category. This is now a + misfiled PR and will not appear in bug report + listings, unless someone explicitly asks a list of all the + misfiled PRs. If you have access to the FreeBSD cluster + machines, you can use query-pr to view a + listing of PRs that have been misfiled: + + &prompt.user; query-pr -q -r gnats-admin | grep -v closed + 52458 gnats-ad open serious medium Re: declaration clash f + 52510 gnats-ad open serious medium Re: lots of sockets in + 52557 gnats-ad open serious medium + 52570 gnats-ad open serious medium Jigdo maintainer update + + Commonly PRs like the ones shown above are misfiled for one + of the following reasons: + + + + A followup to an existing PR, sent through email, has + the wrong format on its Subject: + header. + + + + When filling the &man.send-pr.1; template, the submitter + forgot to set the category or class of the PR to a proper + value. + + + + It is not a real PR, but some random message sent to + bug-followup@freebsd.org or + freebsd-gnats-submit@freebsd.org. + + + +
+ Followups misfiled as new PRs + + 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 + listens to for incoming messages, the subject + of the reply should always be of the form: + + Subject: Re: category/number: old synopsis text + + Most mailers will add the + Re:  part when you + reply to the original mail message of a PR. The + category/number:  part + is a GNATS-specific convention that you have to manually + insert to the subject of your followup reports. + + 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 bug-followup@freebsd.org). Then + the misfiled PR can be closed with a message similar + to: + + 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 + + Searching with query-pr for the + original PR, of which a misfiled followup is a reply, is as + easy as running: + + &prompt.user; query-pr -q -y "some text" + + After you locate the original PR and the misfiled + followups, use the option of + query-pr to save the full text of all the + relevant PRs in a Unix mailbox file, i.e.: + + &prompt.user; query-pr -F 52458 52474 > mbox + + Now you can use any mail user agent to view all the PRs + you saved in mbox. Copy the text of all + the misfiled PRs in a followup to the original PR and make + sure you include the proper Subject: + 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 closed. Make sure you + provide enough details in the log about the reason of this state + change. Typically something like the following is ok: + + Followup to ports/45364 misfiled as a new PR. +This was misfiled because the subject didn't have the format: + + Re: ports/45364: ... + + This way the submitter of the misfiled PR will know what to + avoid the next time a followup to an existing PR is sent. +
+ +
+ PRs misfiled because of missing fields + + The second type of misfiled PRs is usually the result of a + submitter who forgot to fill all the necessary fields when + writing the original PR. + + Missing or bogus category or + class 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. + + Another common cause of misfiled PRs because of formatting + issues is quoting, changes or removal of the + send-pr template, either by the user who + edits the template or by mailers who do strange things to + plain text messages. This doesn't happen a lot of the time, + but it can be fixed with edit-pr too; it + does require a bit of work from the developer who refiles the + PR, but it's relatively easy to do most of the time. +
+ +
+ Misfiled PRs that are not really problem reports + + Some times 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 send + to freebsd-gnats-submit@freebsd.org have to + follow the template of send-pr but email + reports sent to &a.bugs;. + + Developers that come across PRs that look like they should + be posted to &a.bugs.name; or some other list should close the + PR, informing the submitter in their state-change log why this + is not really a PR and where the message should be posted. + + The email addresses that GNATS 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. Every day several messages with + advertisements would reach GNATS which promptly files them all + under the pending 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. + + Currently, with the installation of some antispam filters, + that check all submissions to the GNATS database, the amount + of spam that reaches the pending state is very + small. + + All developers who have access to the FreeBSD.org cluster + machines are encouraged to check for misfiled PRs immediately + close those that are spam mail. Whenever you close one of + these PRs it is also a good idea to set its category to + junk. Junk PRs are not + backed up, so filing spam mail under this category makes it + obvious that we do not care to keep around and waste disk + space for it. +
+
-
+
Further Reading This is a list of resources relevant to the proper writing