diff --git a/en_US.ISO8859-1/articles/Makefile b/en_US.ISO8859-1/articles/Makefile index 8b6ccb9278..aba51703fa 100644 --- a/en_US.ISO8859-1/articles/Makefile +++ b/en_US.ISO8859-1/articles/Makefile @@ -1,40 +1,41 @@ # $FreeBSD$ SUBDIR = SUBDIR+= committers-guide SUBDIR+= console-server SUBDIR+= contributing SUBDIR+= contributors SUBDIR+= cvs-freebsd SUBDIR+= cvsup-advanced SUBDIR+= dialup-firewall SUBDIR+= diskless-x SUBDIR+= euro SUBDIR+= explaining-bsd SUBDIR+= filtering-bridges SUBDIR+= fonts SUBDIR+= formatting-media SUBDIR+= freebsd-questions SUBDIR+= hubs SUBDIR+= ipsec-must SUBDIR+= laptop SUBDIR+= java-tomcat SUBDIR+= mh SUBDIR+= multi-os SUBDIR+= new-users +SUBDIR+= pr-guidelines SUBDIR+= problem-reports SUBDIR+= programming-tools SUBDIR+= pxe SUBDIR+= releng SUBDIR+= releng-packages SUBDIR+= serial-uart SUBDIR+= solid-state SUBDIR+= storage-devices SUBDIR+= vinum SUBDIR+= vm-design SUBDIR+= zip-drive # ROOT_SYMLINKS+= new-users DOC_PREFIX?= ${.CURDIR}/../.. .include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/pr-guidelines/Makefile b/en_US.ISO8859-1/articles/pr-guidelines/Makefile new file mode 100644 index 0000000000..36fc8e67d0 --- /dev/null +++ b/en_US.ISO8859-1/articles/pr-guidelines/Makefile @@ -0,0 +1,16 @@ +# $FreeBSD$ + +DOC?= article + +FORMATS?= html + +INSTALL_COMPRESSED?=gz +INSTALL_ONLY_COMPRESSED?= + +JADEFLAGS+= -V %generate-article-toc% + +SRCS= article.sgml + +DOC_PREFIX?= ${.CURDIR}/../../.. + +.include "${DOC_PREFIX}/share/mk/doc.project.mk" diff --git a/en_US.ISO8859-1/articles/pr-guidelines/article.sgml b/en_US.ISO8859-1/articles/pr-guidelines/article.sgml new file mode 100644 index 0000000000..205e222c8e --- /dev/null +++ b/en_US.ISO8859-1/articles/pr-guidelines/article.sgml @@ -0,0 +1,289 @@ + + + + +
+ + + 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 the quality process, the + correct use of Gnats is essential to the forward progress of the + Project. + + Access to Gnats is provided 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 + have been established covering common aspects of bug management + such as presenting followup, handling close requests and so + forth. +
+ +
+ Problem Report Life-cycle + + + + The originator submits a PR and receives a confirmation + message. + + + + 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 + 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 feedback 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 big 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. + +
+ +
+ Problem Report State + + It is important to update the state of a PR when some + actions are taken. The state should accurately reflect the + current state of work on the PR. + + + A small example on when to change a 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 the 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 some issues (MFC, or + maybe confirmation from originator) are still open. + + + + + 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 use + suspended for wish-list + items that entail a significant amount of work that 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, in that you may go directly change to this state if + the originator cannot test the patch, given that it + works. + +
+ +
+ 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 whatever is missing from the one + you keep open in a followup, with references to the PRs you + close. +
+ +
+ Stale PRs + + A PR is considered stale if it hasn't been modified in + more than six months. Apply the following procedure: + + + + 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 if the person + who corrected 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 all 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 Feedback timeout. + + +
+
+