diff --git a/en_US.ISO8859-1/articles/pr-guidelines/article.sgml b/en_US.ISO8859-1/articles/pr-guidelines/article.sgml index 7f139b0b78..766780e0fe 100644 --- a/en_US.ISO8859-1/articles/pr-guidelines/article.sgml +++ b/en_US.ISO8859-1/articles/pr-guidelines/article.sgml @@ -1,301 +1,317 @@ %man; ]>
Problem Report Handling Guidelines $FreeBSD$ These guidelines describe recommended handling practices for FreeBSD Problem Reports (PRs). Whilst developed for the FreeBSD PR Database Maintenance Team freebsd-bugbusters@FreeBSD.org, these guidelines should be followed by anyone working with FreeBSD PRs. Dag-Erling Smørgrav Hiten Pandya
Introduction GNATS is a defect management (bug reporting) system used by the FreeBSD 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. 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 consistent user experience, guidelines have been established covering common aspects of bug management such as presenting followup, handling close requests, and so 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. 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. 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 analyzed. 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 feedback. A couple of iterations later, both Joe and the originator are satisfied with the patch, and Joe commits it to -CURRENT (or directly to -STABLE if the problem does not exist in -CURRENT), 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. If the patch does not need MFCing, Joe then closes the PR. If the patch needs MFCing, Joe leaves the Problem Report in patched state until the patch has been MFCed, then closes it. 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 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 re-open the PR. The email address 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.
Problem Report State 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. A small example on when to change PR state 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 its state to feedback. At this point, the originator should evaluate the fix in their context and respond indicating whether the defect has indeed been remedied. A Problem Report may be in one of the following states: open Initial state; the problem has been pointed out and it needs reviewing. analyzed The problem has been reviewed and a solution is being sought. feedback Further work requires additional information from the originator or the community; possibly information regarding the proposed solution. patched A patch has been committed, but something (MFC, or maybe confirmation from originator) is still pending. suspended The problem is not being worked on, due to lack of 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 uses suspended for wish-list items that entail a significant amount of work which no one currently has time for. closed A problem report is closed when any changes have been integrated, documented, and tested, or when fixing the problem is abandoned. The patched state is directly related to feedback, so you may go directly to closed state if the originator cannot test the patch, and it works in your own testing.
Types of Problem Reports
Assigned PRs If a PR has the responsible field set to the username of a FreeBSD developer, it means that the PR has been handed over to that particular person for further work. Assigned PRs should not be touched by anyone but the 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 you please.
Duplicate PRs If you find more than one PR that describe the same issue, 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 all the missing information to one in a followup, including references to the others; then close 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: If the PR contains sufficient detail, try to reproduce the problem in -CURRENT and -STABLE. If you succeed, submit a followup detailing your findings and try to find someone to assign it to. Set the state to analyzed if appropriate. If the PR describes an issue which you know is the result of a usage error (incorrect configuration or otherwise), submit a followup explaining what the originator did wrong, then close the PR with the reason User error or Configuration error. If the PR describes an error which you know has been corrected in both -CURRENT and -STABLE, close it with a message stating when it was fixed in each branch. If the PR describes an error which you know has been corrected in -CURRENT, but not in -STABLE, 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 feedback and assign it to whomever will do the MFC. 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 notation Feedback timeout.
+ +
+ Further Reading + + This is a list of resources relevant to the proper writing + and processing of problem reports. It is by no means complete. + + + + How to + Write FreeBSD Problem Reports—guidelines + for PR originators. + + +