917 lines
30 KiB
Text
917 lines
30 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-unassigned">PRs not yet assigned to anyone.</link></para>
|
|
</listitem>
|
|
<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-unassigned">
|
|
<title>Unassigned PRs</title>
|
|
|
|
<para>When PRs arrive, they are initially assigned to a generic
|
|
(placeholder) assignee. These are always prepended with
|
|
<literal>freebsd-</literal>. The exact value for this default
|
|
depends on the category; in most cases, it corresponds to a
|
|
specific &os; mailing list. Here is the current list, with
|
|
the most common ones listed first:</para>
|
|
|
|
<table id=default-assignees-common>
|
|
<title>Default Assignees — most common</title>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Type</entry>
|
|
<entry>Categories</entry>
|
|
<entry>Default Assignee</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry>base system</entry>
|
|
<entry>bin, conf, gnu, kern, misc</entry>
|
|
<entry>freebsd-bugs</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>architecture-specific</entry>
|
|
<entry>alpha, i386, ia64, powerpc, sparc64</entry>
|
|
<entry>freebsd-<replaceable>arch</replaceable></entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>ports collection</entry>
|
|
<entry>ports</entry>
|
|
<entry>freebsd-ports-bugs</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>documentation shipped with the system</entry>
|
|
<entry>docs</entry>
|
|
<entry>freebsd-doc</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>&os; web pages (not including docs)</entry>
|
|
<entry>www</entry>
|
|
<entry>freebsd-www</entry>
|
|
</row>
|
|
</tbody>
|
|
</table>
|
|
|
|
<table id=default-assignees-other>
|
|
<title>Default Assignees — other</title>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Type</entry>
|
|
<entry>Categories</entry>
|
|
<entry>Default Assignee</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry>advocacy efforts</entry>
|
|
<entry>advocacy</entry>
|
|
<entry>freebsd-advocacy</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>&java.virtual.machine; problems</entry>
|
|
<entry>java</entry>
|
|
<entry>freebsd-java</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>standards compliance</entry>
|
|
<entry>standards</entry>
|
|
<entry>freebsd-standards</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>threading libraries</entry>
|
|
<entry>threads</entry>
|
|
<entry>freebsd-threads</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>&man.usb.4; subsystem</entry>
|
|
<entry>usb</entry>
|
|
<entry>freebsd-usb</entry>
|
|
</row>
|
|
</tbody>
|
|
</table>
|
|
|
|
<para>Do not be surprised to find that the submitter of the
|
|
PR has assigned it to the wrong category. If you fix the
|
|
category, do not forget to fix the assignment as well.
|
|
(In particular, our submitters seem to have a hard time
|
|
understanding that just because their problem manifested
|
|
on an i386 system, that it might be generic to all of &os;,
|
|
and thus be more appropriate for <literal>kern</literal>.
|
|
The converse is also true, of course.)</para>
|
|
|
|
<para>Certain PRs may be reassigned away from these generic
|
|
assignees by anyone. For assignees which are mailing lists,
|
|
please use the long form when making the assignment (e.g.,
|
|
<literal>freebsd-foo</literal> instead of <literal>foo</literal>);
|
|
this will avoid duplicate emails sent to the mailing list.</para>
|
|
|
|
<note>
|
|
<para>Here is a sample list of such entities; it is probably
|
|
not complete. In some cases, entries that have the short form are
|
|
<emphasis>aliases</emphasis>, not mailing lists.</para>
|
|
</note>
|
|
|
|
<table id=common-assignees-base>
|
|
<title>Common Assignees — base system</title>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Type</entry>
|
|
<entry>Suggested Category</entry>
|
|
<entry>Suggested Assignee</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry>problem specific to the &arm; architecture</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-arm</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem specific to the &mips; architecture</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-mips</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem specific to the &powerpc; architecture</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-ppc</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with Advanced Configuration and Power
|
|
Management (&man.acpi.4;)</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-acpi</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with Asynchronous Transfer Mode (ATM)
|
|
drivers</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-atm</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with embedded or small-footprint &os;
|
|
systems (e.g., NanoBSD/PicoBSD/FreeBSD-arm)</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-embedded</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with &firewire; drivers</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-firewire</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with the filesystem code</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-fs</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with the &man.geom.4; subsystem</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-geom</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with the &man.ipfw.4; subsystem</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-ipfw</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with Integrated Services Digital Network
|
|
(ISDN) drivers</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-isdn</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with &linux; or SVR4 emulation</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-emulation</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with the networking stack</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-net</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with the &man.pf.4; subsystem</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-pf</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with the &man.scsi.4; subsystem</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-scsi</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with the &man.sound.4; subsystem</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-multimedia</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with &man.sysinstall.8;</entry>
|
|
<entry>bin</entry>
|
|
<entry>freebsd-qa</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with the system startup scripts
|
|
(&man.rc.8;)</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-rc</entry>
|
|
</row>
|
|
</tbody>
|
|
</table>
|
|
|
|
<table id=common-assignees-ports>
|
|
<title>Common Assignees — Ports Collection</title>
|
|
<tgroup cols="3">
|
|
<thead>
|
|
<row>
|
|
<entry>Type</entry>
|
|
<entry>Suggested Category</entry>
|
|
<entry>Suggested Assignee</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry>problem with the ports framework
|
|
(<emphasis>not</emphasis> with an individual port!)</entry>
|
|
<entry>ports</entry>
|
|
<entry>portmgr</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by apache@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>apache</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by eclipse@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>freebsd-eclipse</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by gnome@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>gnome</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by haskell@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>haskell</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by java@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>freebsd-java</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by kde@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>kde</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by
|
|
openoffice@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>freebsd-openoffice</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by perl@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>perl</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by python@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>freebsd-python</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by x11@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>freebsd-x11</entry>
|
|
</row>
|
|
</tbody>
|
|
</table>
|
|
|
|
<para>Ports PRs which have a maintainer who is a ports committer
|
|
may be reassigned by anyone (but note that not every &os;
|
|
committer is necessarily a ports committer, so you cannot
|
|
simply go by the email address alone.)
|
|
</para>
|
|
|
|
<para>For other PRs, please do not reassign them to individuals
|
|
(other than yourself) unless you are certain that the assignee
|
|
really wants to track the PR. This will help to avoid the
|
|
case where no one looks at fixing a particular problem
|
|
because everyone assumes that the assignee is already working
|
|
on it.</para>
|
|
|
|
</section>
|
|
|
|
<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>A submitter sent a Cc: to a mailing list and someone
|
|
followed up to that post instead of the email issued by
|
|
GNATS after processing. The email to the list will not
|
|
have the category/PRnumber tracking tag. (This is why we
|
|
discourage submitters from doing this exact thing.)</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>When completing the &man.send-pr.1; template, the submitter
|
|
set Confidential to <literal>yes</literal>. (Since we allow
|
|
anyone to mirror GNATS via <application>cvsup</application>,
|
|
our PRs are public information. Security alerts should
|
|
therefore not be sent via GNATS but instead via email to
|
|
the Security Team.)</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 &a.bugfollowup;). 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 did not 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 does not 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. Spam messages
|
|
that reach GNATS are promptly filed
|
|
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, please do the following:
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Set Category to <literal>junk</literal>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Set Confidential to <literal>no</literal>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Set Responsible to yourself (and not, e.g.,
|
|
<literal>freebsd-bugs</literal>, which merely
|
|
sends more mail).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Set State to <literal>closed</literal>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>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. If you merely close them without changing the
|
|
category, they remain both in the master database and in
|
|
any copies of the database mirrored through
|
|
<application>cvsup</application>.</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>
|