os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

PR handling guidelines distilled from archived discussions on the

Browse source 
buggers mailing list.

Submitted by:	Hiten Pandya <hiten@uk.FreeBSD.org>
This commit is contained in:
Dag-Erling Smørgrav 2002-05-09 12:28:53 +00:00
parent 038e215337
commit bd71c85c4d
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=13011
3 changed files with 306 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
en_US.ISO8859-1/articles/Makefile
View file

@ -22,6 +22,7 @@ SUBDIR+= java-tomcat
SUBDIR+= mh
SUBDIR+= multi-os
SUBDIR+= new-users
SUBDIR+= pr-guidelines
SUBDIR+= problem-reports
SUBDIR+= programming-tools
SUBDIR+= pxe

16
en_US.ISO8859-1/articles/pr-guidelines/Makefile Normal file
View file

@ -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"

289
en_US.ISO8859-1/articles/pr-guidelines/article.sgml Normal file
View file

@ -0,0 +1,289 @@
<!--
Problem Report Handling Guidelines
The FreeBSD Project - http://www.FreeBSD.org
-->
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN">
<article>
<!-- :START of Article Metadata -->
<articleinfo>
<title>Problem Report Handling Guidelines</title>
<pubdate>$FreeBSD$</pubdate>
<abstract>
<para>These guidelines describe recommended handling practices
for FreeBSD Problem Reports (PRs). Whilst developed for the
FreeBSD PR Database Maintenance Team
<email>freebsd-bugbusters@FreeBSD.org</email>, these
guidelines should be followed by anyone working with FreeBSD
PRs.</para>
</abstract>
<authorgroup>
<author>
<firstname>Dag-Erling</firstname>
<surname>Sm&oslash;rgrav</surname>
</author>
<author>
<firstname>Hiten</firstname>
<surname>Pandya</surname>
</author>
</authorgroup>
</articleinfo>
<!-- :END of Article Metadata-->
<section>
<title>Introduction</title>
<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
Project.</para>
<para>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.</para>
</section>
<section>
<title>Problem Report Life-cycle</title>
<itemizedlist>
<listitem>
<para>The originator submits a PR and receives a confirmation
message.</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
him.</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>
</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>
</listitem>
<listitem>
<para>A couple of iterations later, both Joe and the
originator are satisfied with the patch, and Joe commits it
to <literal>-CURRENT</literal> (or directly to
<literal>-STABLE</literal> if the problem does not exist in
<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>
</listitem>
<listitem>
<para>If the patch does not need MFCing, Joe then closes the
PR.</para>
</listitem>
<listitem>
<para>If the patch needs MFCing, Joe leaves the Problem Report
in <quote>feedback</quote> state until the patch has been
MFCed, then closes it.</para>
</listitem>
</itemizedlist>
<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
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.</para>
</note>
</section>
<section>
<title>Problem Report State</title>
<para>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.</para>
<example>
<title>A small example on when to change a 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
<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>
</example>
<para>A Problem Report may be in one of the following
states:</para>
<glosslist>
<glossentry>
<glossterm>open</glossterm>
<glossdef>
<para>Initial state; the problem has been pointed out and it
needs reviewing.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>analyzed</glossterm>
<glossdef>
<para>The problem has been reviewed and a
solution is being sought.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>feedback</glossterm>
<glossdef>
<para>Further work requires additional information from the
originator or the community; possibly information
regarding the proposed solution.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>patched</glossterm>
<glossdef>
<para>A patch has been committed, but some issues (MFC, or
maybe confirmation from originator) are still open.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>suspended</glossterm>
<glossdef>
<para>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
<quote>suspended</quote> for <quote>wish-list</quote>
items that entail a significant amount of work that no one
currently has time for.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm>closed</glossterm>
<glossdef>
<para>A problem report is closed when any changes have been
integrated, documented, and tested, or when fixing the
problem is abandoned.</para>
</glossdef>
</glossentry>
</glosslist>
<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>
</note>
</section>
<section>
<title>Types of Problem Reports</title>
<section>
<title>Assigned PRs</title>
<para>If a PR has the <literal>responsible</literal> 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.</para>
<para>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.</para>
</section>
<section>
<title>Duplicate PRs</title>
<para>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.</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>
<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
followup detailing your findings and try to find someone
to assign it to. Set the state to <quote>analyzed</quote>
if appropriate.</para>
</listitem>
<listitem>
<para>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
<quote>User error</quote> or <quote>Configuration
error</quote>.</para>
</listitem>
<listitem>
<para>If the PR describes an error which you know has been
corrected in both <literal>-CURRENT</literal> and
<literal>-STABLE</literal>, close it with a message
stating when it was fixed in each branch. </para>
</listitem>
<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
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
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>
</listitem>
</itemizedlist>
</section>
</section>
</article>