dc43212418
alias vs. individual). Provide a crossref to the signup page on the wiki where individuals can ask for certain issues to be assigned to them by default.
1059 lines
34 KiB
Text
1059 lines
34 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>repocopy</glossterm>
|
|
<glossdef>
|
|
<para>The resolution of the problem report is dependent on a
|
|
repository copy, or repocopy, operation within the CVS
|
|
repository which is awaiting completion.</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, amd64, arm, i386, ia64, powerpc, sparc64, sun4v</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. There are several types of assignees:
|
|
specialized mailing lists; mail aliases (used for certain
|
|
limited-interest items); and individuals.</para>
|
|
|
|
<para>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>Since the list of individuals who have volunteered to
|
|
be the default assignee for certain types of PRs changes
|
|
so often, it is much more suitable for <ulink
|
|
url="http://wiki.freebsd.org/AssigningPRs">the FreeBSD wiki</ulink>.
|
|
</para>
|
|
</note>
|
|
|
|
<para>Here is a sample list of such entities; it is probably
|
|
not complete.</para>
|
|
|
|
<table id=common-assignees-base>
|
|
<title>Common Assignees — base system</title>
|
|
<tgroup cols="4">
|
|
<thead>
|
|
<row>
|
|
<entry>Type</entry>
|
|
<entry>Suggested Category</entry>
|
|
<entry>Suggested Assignee</entry>
|
|
<entry>Assignee Type</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry>problem specific to the &arm; architecture</entry>
|
|
<entry>arm</entry>
|
|
<entry>freebsd-arm</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem specific to the &mips; architecture</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-mips</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem specific to the &powerpc; architecture</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-ppc</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with Advanced Configuration and Power
|
|
Management (&man.acpi.4;)</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-acpi</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with Asynchronous Transfer Mode (ATM)
|
|
drivers</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-atm</entry>
|
|
<entry>mailing list</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>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with &firewire; drivers</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-firewire</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with the filesystem code</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-fs</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with the &man.geom.4; subsystem</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-geom</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with the &man.ipfw.4; subsystem</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-ipfw</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with Integrated Services Digital Network
|
|
(ISDN) drivers</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-isdn</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>&man.jail.8; subsystem</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-jail</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with &linux; or SVR4 emulation</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-emulation</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with the networking stack</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-net</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with the &man.pf.4; subsystem</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-pf</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with the &man.scsi.4; subsystem</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-scsi</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with the &man.sound.4; subsystem</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-multimedia</entry>
|
|
<entry>alias</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with &man.sysinstall.8;</entry>
|
|
<entry>bin</entry>
|
|
<entry>freebsd-bugs (<emphasis>not</emphasis> freebsd-qa)</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with the system startup scripts
|
|
(&man.rc.8;)</entry>
|
|
<entry>kern</entry>
|
|
<entry>freebsd-rc</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with Xen emulation</entry>
|
|
<entry>kern</entry>
|
|
<entry>xen</entry>
|
|
<entry>alias</entry>
|
|
</row>
|
|
</tbody>
|
|
</table>
|
|
|
|
<table id=common-assignees-ports>
|
|
<title>Common Assignees — Ports Collection</title>
|
|
<tgroup cols="4">
|
|
<thead>
|
|
<row>
|
|
<entry>Type</entry>
|
|
<entry>Suggested Category</entry>
|
|
<entry>Suggested Assignee</entry>
|
|
<entry>Assignee Type</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>
|
|
<entry>alias</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by apache@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>apache</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by autotools@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>autotools</entry>
|
|
<entry>alias</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by doceng@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>doceng</entry>
|
|
<entry>alias</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by eclipse@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>freebsd-eclipse</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by gecko@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>gecko</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by gnome@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>gnome</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by hamradio@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>hamradio</entry>
|
|
<entry>alias</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by haskell@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>haskell</entry>
|
|
<entry>alias</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by java@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>freebsd-java</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by kde@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>kde</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by mono@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>mono</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by
|
|
openoffice@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>freebsd-openoffice</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by perl@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>perl</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by python@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>freebsd-python</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by ruby@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>freebsd-ruby</entry>
|
|
<entry>mailing list</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by secteam@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>secteam</entry>
|
|
<entry>alias</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by vbox@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>vbox</entry>
|
|
<entry>alias</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>port which is maintained by x11@FreeBSD.org</entry>
|
|
<entry>ports</entry>
|
|
<entry>freebsd-x11</entry>
|
|
<entry>mailing list</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>
|
|
|
|
<table id=common-assignees-other>
|
|
<title>Common Assignees — Other</title>
|
|
<tgroup cols="4">
|
|
<thead>
|
|
<row>
|
|
<entry>Type</entry>
|
|
<entry>Suggested Category</entry>
|
|
<entry>Suggested Assignee</entry>
|
|
<entry>Assignee Type</entry>
|
|
</row>
|
|
</thead>
|
|
|
|
<tbody>
|
|
<row>
|
|
<entry>problem with GNATS itself (&man.send-pr.1;)</entry>
|
|
<entry>bin</entry>
|
|
<entry>bugmeister</entry>
|
|
<entry>alias</entry>
|
|
</row>
|
|
|
|
<row>
|
|
<entry>problem with GNATS web form</entry>
|
|
<entry>www</entry>
|
|
<entry>bugmeister</entry>
|
|
<entry>alias</entry>
|
|
</row>
|
|
</tbody>
|
|
</table>
|
|
|
|
</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 or bugmeister. 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>patched</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:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Set Category to <literal>junk</literal>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Set Confidential to <literal>no</literal>.</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>
|