doc/en_US.ISO8859-1/articles/pr-guidelines/article.sgml

<!--
	Problem Report Handling Guidelines
	The FreeBSD Project - http://www.FreeBSD.org
-->

<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;
]>

<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 FreeBSD's quality, the
      correct use of GNATS is essential to the forward progress of the
      Project.</para>

    <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 consistent 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 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 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>patched</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 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.</para>
    </note>
    <note>
      <para>The <quote>email address</quote> 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.</para>
    </note>
  </section>

  <section>
    <title>Problem Report State</title>

    <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 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 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>
    </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 something (MFC, or
	    maybe confirmation from originator) is still pending.</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 uses
	    <quote>suspended</quote> for <quote>wish-list</quote>
	    items that entail a significant amount of work which 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, 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>

  <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 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 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
	    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 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 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 <quote>Feedback timeout</quote>.</para>
	</listitem>
      </itemizedlist>
    </section>
  </section>
</article>