5fa082b1f8
Currently we have articles.ent and books.ent, and
for example, articles.ent can be used by putting the
following lines in the doctype declaration:
<!ENTITY % articles.ent PUBLIC
"-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN">
%articles.ent;
This pulls all of the necessary entities via share/sgml/articles.ent.
The translation teams can customize these entities by redefining
the articles.ent file in <langcode>/share/sgml. See
ja_JP.eucJP/share/sgml for example.
530 lines
20 KiB
Text
530 lines
20 KiB
Text
<!--
|
|
Problem Report Handling Guidelines
|
|
The FreeBSD Project - http://www.FreeBSD.org
|
|
-->
|
|
|
|
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
|
|
<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN">
|
|
%articles.ent;
|
|
<!ENTITY man.edit-pr.1 "<citerefentry/<refentrytitle/edit-pr/<manvolnum/1//">
|
|
<!ENTITY man.query-pr.1 "<citerefentry/<refentrytitle/query-pr/<manvolnum/1//">
|
|
]>
|
|
|
|
<article>
|
|
<!-- :START of Article Metadata -->
|
|
<articleinfo>
|
|
<title>Problem Report Handling Guidelines</title>
|
|
|
|
<pubdate>$FreeBSD$</pubdate>
|
|
|
|
<legalnotice id="trademarks" role="trademarks">
|
|
&tm-attrib.freebsd;
|
|
&tm-attrib.opengroup;
|
|
&tm-attrib.general;
|
|
</legalnotice>
|
|
|
|
<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ørgrav</surname>
|
|
</author>
|
|
|
|
<author>
|
|
<firstname>Hiten</firstname>
|
|
<surname>Pandya</surname>
|
|
</author>
|
|
</authorgroup>
|
|
</articleinfo>
|
|
<!-- :END of Article Metadata-->
|
|
|
|
<section id="intro">
|
|
<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 id="pr-lifecycle">
|
|
<title>Problem Report Life-cycle</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The Reporter submits a PR with &man.send-pr.1; 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 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 id="pr-states">
|
|
<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 id="pr-types">
|
|
<title>Types of Problem Reports</title>
|
|
|
|
<para>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.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><link linkend="pr-assigned">PRs already assigned to someone.</link></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><link linkend="pr-dups">Duplicates of existing PRs.</link></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><link linkend="pr-stale">Stale PRs</link></para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><link linkend="pr-misfiled">Misfiled PRs</link></para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>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.</para>
|
|
|
|
<section id="pr-assigned">
|
|
<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 id="pr-dups">
|
|
<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 id="pr-stale">
|
|
<title>Stale PRs</title>
|
|
|
|
<para>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:</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 id="pr-misfiled">
|
|
<title>Misfiled PRs</title>
|
|
|
|
<para>GNATS is picky about the format of a submitted bug report.
|
|
This is why a lot of PRs end up being <quote>misfiled</quote> if
|
|
the submitter forgets to fill in a field or puts the wrong sort of
|
|
data in some of the PR fields. This section aims to provide most
|
|
of the necessary details for FreeBSD developers that can help them to
|
|
close or refile these PRs.</para>
|
|
|
|
<para>When GNATS cannot deduce what to do with a problem report
|
|
that reaches the database, it sets the responsible of the PR to
|
|
<literal>gnats-admin</literal> and files it under the
|
|
<literal>pending</literal> category. This is now a
|
|
<quote>misfiled</quote> PR and will not appear in bug report
|
|
listings, unless someone explicitly asks for a list of all the
|
|
misfiled PRs. If you have access to the FreeBSD cluster
|
|
machines, you can use <command>query-pr</command> to view a
|
|
listing of PRs that have been misfiled:</para>
|
|
|
|
<screen>&prompt.user; <userinput>query-pr -x -q -r gnats-admin</userinput>
|
|
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</screen>
|
|
|
|
<para>Commonly PRs like the ones shown above are misfiled for one
|
|
of the following reasons:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>A followup to an existing PR, sent through email, has
|
|
the wrong format on its <literal>Subject:</literal>
|
|
header.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>When completing the &man.send-pr.1; template, the submitter
|
|
forgot to set the category or class of the PR to a proper
|
|
value.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>It is not a real PR, but some random message sent to
|
|
<email>bug-followup@FreeBSD.org</email> or
|
|
<email>freebsd-gnats-submit@FreeBSD.org</email>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<section id="pr-misfiled-followups">
|
|
<title>Followups misfiled as new PRs</title>
|
|
|
|
<para>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
|
|
<quote>listens</quote> to for incoming messages, the subject
|
|
of the reply should always be of the form:</para>
|
|
|
|
<programlisting>Subject: Re: category/number: old synopsis text</programlisting>
|
|
|
|
<para>Most mailers will add the
|
|
<quote><literal>Re: </literal></quote> part when you
|
|
reply to the original mail message of a PR. The
|
|
<quote><literal>category/number: </literal></quote> part
|
|
is a GNATS-specific convention that you have to manually
|
|
insert to the subject of your followup reports.</para>
|
|
|
|
<para>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 <email>bug-followup@FreeBSD.org</email>). Then
|
|
the misfiled PR can be closed with a message similar
|
|
to:</para>
|
|
|
|
<programlisting>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</programlisting>
|
|
|
|
<para>Searching with <command>query-pr</command> for the
|
|
original PR, of which a misfiled followup is a reply, is as
|
|
easy as running:</para>
|
|
|
|
<screen>&prompt.user; query-pr -q -y "some text"</screen>
|
|
|
|
<para>After you locate the original PR and the misfiled
|
|
followups, use the <option>-F</option> option of
|
|
<command>query-pr</command> to save the full text of all the
|
|
relevant PRs in a &unix; mailbox file, i.e.:</para>
|
|
|
|
<screen>&prompt.user; <userinput>query-pr -F 52458 52474 > mbox</userinput></screen>
|
|
|
|
<para>Now you can use any mail user agent to view all the PRs
|
|
you saved in <filename>mbox</filename>. Copy the text of all
|
|
the misfiled PRs in a followup to the original PR and make
|
|
sure you include the proper <literal>Subject:</literal>
|
|
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 <quote>closed</quote>. Make sure you
|
|
provide enough details in the log about the reason of this state
|
|
change. Typically something like the following is ok:</para>
|
|
|
|
<programlisting>Followup to ports/45364 misfiled as a new PR.
|
|
This was misfiled because the subject didn't have the format:
|
|
|
|
Re: ports/45364: ...</programlisting>
|
|
|
|
<para>This way the submitter of the misfiled PR will know what to
|
|
avoid the next time a followup to an existing PR is sent.</para>
|
|
</section>
|
|
|
|
<section id="pr-misfiled-format">
|
|
<title>PRs misfiled because of missing fields</title>
|
|
|
|
<para>The second type of misfiled PRs is usually the result of a
|
|
submitter forgetting to fill all the necessary fields when
|
|
writing the original PR.</para>
|
|
|
|
<para>Missing or bogus <quote>category</quote> or
|
|
<quote>class</quote> 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.</para>
|
|
|
|
<para>Another common cause of misfiled PRs because of formatting
|
|
issues is quoting, changes or removal of the
|
|
<command>send-pr</command> template, either by the user who
|
|
edits the template or by mailers which do strange things to
|
|
plain text messages. This doesn't happen a lot of the time,
|
|
but it can be fixed with <command>edit-pr</command> too; it
|
|
does require a bit of work from the developer who refiles the
|
|
PR, but it is relatively easy to do most of the time.</para>
|
|
</section>
|
|
|
|
<section id="pr-misfiled-notpr">
|
|
<title>Misfiled PRs that are not really problem reports</title>
|
|
|
|
<para>Sometimes 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 sent
|
|
to <email>freebsd-gnats-submit@FreeBSD.org</email> have to
|
|
follow the template of <command>send-pr</command>, but email
|
|
reports can be sent to &a.bugs;.</para>
|
|
|
|
<para>Developers that come across PRs that look like they should have
|
|
been 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.</para>
|
|
|
|
<para>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 <quote>pending</quote> 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.</para>
|
|
|
|
<para>Currently, with the installation of some antispam filters
|
|
that check all submissions to the GNATS database, the amount
|
|
of spam that reaches the <quote>pending</quote> state is very
|
|
small.</para>
|
|
|
|
<para>All developers who have access to the FreeBSD.org cluster
|
|
machines are encouraged to check for misfiled PRs and 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
|
|
<quote><literal>junk</literal></quote>. Junk PRs are not
|
|
backed up, so filing spam mail under this category makes it
|
|
obvious that we do not care to keep it around or waste disk
|
|
space for it.</para>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="references">
|
|
<title>Further Reading</title>
|
|
|
|
<para>This is a list of resources relevant to the proper writing
|
|
and processing of problem reports. It is by no means complete.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><ulink
|
|
url="&url.articles.problem-reports;/article.html">How to
|
|
Write FreeBSD Problem Reports</ulink>—guidelines
|
|
for PR originators.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</article>
|