. Add a section on misfiled bug reports (possible causes and some
comments on their handling). . Add references to the mailing list entities and use them in the text. . Add id="foo" keywords to the sections of the article to make links other people make to parts of the article less prone to breaking.
This commit is contained in:
Giorgos Keramidas
parent
096648e07a
commit
3715e28494
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=17080
1 changed files with 223 additions and 14 deletions
|
|
@ -6,6 +6,10 @@
|
|||
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
|
||||
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
|
||||
%man;
|
||||
<!ENTITY % mailing-lists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//EN">
|
||||
%mailing-lists;
|
||||
<!ENTITY man.edit-pr.1 "<citerefentry/<refentrytitle/edit-pr/<manvolnum/1//">
|
||||
<!ENTITY man.query-pr.1 "<citerefentry/<refentrytitle/query-pr/<manvolnum/1//">
|
||||
]>
|
||||
|
||||
<article>
|
||||
|
|
@ -38,7 +42,7 @@
|
|||
</articleinfo>
|
||||
<!-- :END of Article Metadata-->
|
||||
|
||||
<section>
|
||||
<section id="intro">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>GNATS is a defect management (bug reporting) system used by
|
||||
|
|
@ -55,15 +59,13 @@
|
|||
forth.</para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<section id="pr-lifecycle">
|
||||
<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>
|
||||
<para>The Reporter submits a PR with &man.send-pr.1; and
|
||||
receives a confirmation message.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
|
|
@ -130,7 +132,7 @@
|
|||
</note>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<section id="pr-states">
|
||||
<title>Problem Report State</title>
|
||||
|
||||
<para>It is important to update the state of a PR when certain
|
||||
|
|
@ -216,10 +218,35 @@
|
|||
</note>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<section id="pr-types">
|
||||
<title>Types of Problem Reports</title>
|
||||
|
||||
<section>
|
||||
<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
|
||||
|
|
@ -235,7 +262,7 @@
|
|||
you please.</para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<section id="pr-dups">
|
||||
<title>Duplicate PRs</title>
|
||||
|
||||
<para>If you find more than one PR that describe the same issue,
|
||||
|
|
@ -247,11 +274,12 @@
|
|||
the other PRs (which are now completely superseded).</para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<section id="pr-stale">
|
||||
<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>
|
||||
<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>
|
||||
|
|
@ -297,9 +325,190 @@
|
|||
</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 a field or puts the wrong sort of
|
||||
data some of the PR fields. This section aims to provide most
|
||||
of the necessary details for FreeBSD developers that can help
|
||||
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 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 -q -r gnats-admin | grep -v closed</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 filling 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 who forgot 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 who 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's 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>Some times 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 send
|
||||
to <email>freebsd-gnats-submit@freebsd.org</email> have to
|
||||
follow the template of <command>send-pr</command> but email
|
||||
reports sent to &a.bugs;.</para>
|
||||
|
||||
<para>Developers that come across PRs that look like they should
|
||||
be 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 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 around and waste disk
|
||||
space for it.</para>
|
||||
</section>
|
||||
</section>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<section id="references">
|
||||
<title>Further Reading</title>
|
||||
|
||||
<para>This is a list of resources relevant to the proper writing
|
||||
|
|
|
|||
Loading…
Reference in a new issue