Subject: [docathon] Converted PR.list
To: None <netbsd-docs@netbsd.org>
From: None <dsieger@techfak.uni-bielefeld.de>
List: netbsd-docs
Date: 04/05/2007 19:36:03
--k+w/mQv8wyuph6w0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
Hi,
attached is a converted htdocs/developers/PR.list file and patch.
Regards,
Daniel
--
Daniel Sieger
Faculty of Technology
Bielefeld University
wwwhomes.uni-bielefeld.de/dsieger
--k+w/mQv8wyuph6w0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="PR.xml"
<?xml version="1.0"?>
<!DOCTYPE webpage
PUBLIC "-//NetBSD//DTD Website-based NetBSD Extension//EN"
"http://www.NetBSD.org/XML/htdocs/lang/share/xml/website-netbsd.dtd">
<webpage id="developers-PR">
<config param="desc" value="Resolving Problem Reports"/>
<config param="cvstag" value="$NetBSD: Exp $"/>
<config param="rcsdate" value="$Date: $"/>
<head>
<title>Resolving Problem Reports</title>
</head>
<sect1 role="toc">
<sect2 id="top">
<title>Resolving Problem Reports</title>
<sect3 id="intro">
<title>Introduction</title>
<para>The NetBSD Project uses the GNATS <quote>Problem Report</quote>
database to accept and track bug/problem reports from all users of
NetBSD. When used properly, this facility allows us to make sure
that no problem with the NetBSD software goes unfixed.</para>
<para>The GNATS database uses Internet E-mail as its principal
submission mechanism, and keeps the problem reports (commonly
abbreviated <quote>PR</quote>) in Internet E-mail format, with an
extended header format in the body of the message. The database uses
one file per PR, and each category is a directory, in a manner
similar to the MH mail system, and NetNews.</para>
</sect3>
<sect3 id="access">
<title>Accessing the Problem Report Database</title>
<sect4 id="webinterface">
<title>Web Interface</title>
<para>There is a web-based interface to the GNATS database that has
both a <ulink url="../Gnats/">tree of database summary pages</ulink>, and a <ulink
url="../Misc/query-pr.html">search</ulink> facility. The web interface
has some limitations:</para>
<itemizedlist>
<listitem>The web interface is several hours behind the actual
database because it operates on a copy of the database for
security.</listitem>
<listitem>The web interface <emphasis>does not</emphasis> provide
access to any PR marked <quote>confidential</quote>.</listitem>
<listitem>PRs displayed by a web browser have been through
sufficient transformation that <quote>cut & paste</quote> is
not likely to do what you expect (i.e. patches will not apply
properly because of white space substitution, uuencoded text
will not decode properly).</listitem>
</itemizedlist>
</sect4>
<sect4 id="netbsd-bugs">
<title>The netbsd-bugs Mailing List</title>
<para>All PRs, confidential or not, are sent to the <ulink
URL="/MailingLists/#netbsd-bugs">netbsd-bugs</ulink> mailing list,
so that subscribers can see each PR as it is added to the
database.</para>
</sect4>
<sect4 id="gnatscommands">
<title>The GNATS commands on gnats.NetBSD.org</title>
<para>The GNATS database lives on the host gnats.NetBSD.org. All
developers are given an account on that host so that they can
directly manipulate PRs, and access confidential PRs. The commands
<command>edit-pr</command> and <command>query-pr</command> live in
<filename>/usr/pkg/bin</filename>; Make sure you have that directory
in your <varname>$PATH</varname>.</para>
<para>There are no UNIX Manual pages for these commands. As with most
GNU software, there are <quote>info</quote> pages available through
the <command>info</command> command. Also, invoking
<command>query-pr</command> without any arguments will cause it to
give its usage message.</para>
<para>The <command>query-pr</command> command is a proper database
query interface; it has a large number of options to search the
database. Once you know the PR number of the PR you wish to
manipulate, you can:</para>
<itemizedlist>
<listitem>
<para><command>query-pr --full</command> <number></para>
<para>This will dump out the full PR without any transformation to
standard output.</para>
</listitem>
<listitem>
<para><command>edit-pr</command> <number></para>
<para>This command will start up a text editor
(<application>vi</application> by default; but this can be
overridden by the <varname>$EDITOR</varname> or
<varname>$VISUAL</varname> environment variables), so that
changes can be made to the PR.</para>
</listitem>
</itemizedlist>
</sect4>
<sect4 id="edit-pr">
<title>The Common Reasons to <command>edit-pr</command></title>
<para>The most common changes made to a PR are:</para>
<orderedlist>
<listitem>
<para>Change the PR's <code>>State:</code> field to one of the values
listed in <ulink URL="../Misc/pr-states.html">state</ulink> as it progresses
through the process of resolving it.</para>
<para>The person listed in the <code>>Responsible:</code> field of the
PR should be making these state changes, as it is necessary.</para>
</listitem>
<listitem>
<para>Change the PR's <code>>Responsible:</code> field to the account name
of a developer who will handle the PR.
This person becomes the PR Submitter's primary contact for
getting the problem resolved.</para>
<para>This field can have any username from /etc/passwd on
<code>gnats.NetBSD.org</code> and anyone listed in the
<filename>/usr/pkg/share/gnats/gnats-db/gnats-adm/responsible</filename>
file.</para>
<para>All PRs get a default Responsible Person when they are
initially filed, appropriate to the category in which the PR
was filed (e.g. <quote>security-officer</quote> for PRs in
the <quote>security</quote> category). The
<filename>/usr/pkg/share/gnats/gnats-db/gnats-adm/categories</filename>
file lists the default Responsible Person for each
category.</para>
<para>There is also a table of <ulink
url="../Gnats/#table-responsible">developers responsible for
current PRs</ulink>.</para>
</listitem>
<listitem>
<para>Change the PR's <code>>Category:</code> field.</para>
<para>It is not unusual for a PR Submitter to have made a poor
category choice. There is a list of <ulink
url="../Gnats/#category-descriptions">PR categories and their
definitions</ulink> and a table of <ulink
url="../Gnats/#table-category">current PRs by
category</ulink>.</para>
<para>The
<filename>/usr/pkg/share/gnats/gnats-db/gnats-adm/categories</filename>
file lists the valid categories and the default Responsible
Person. It is usually necessary to change the
<code>>Responsible:</code> field at the same time to a more
appropriate person. Most often, the correct Responsible Person
is the default Responsible Person for the new category.</para>
</listitem>
<listitem>
<para>Change other <ulink url="../Misc/pr-fields.html">PR
Fields</ulink> according to the analysis of the responsible
developer.</para>
</listitem>
</orderedlist>
<para>Edit each field you think needs modifying, then save the file
and exit the editor. The <command>edit-pr</command> will then
prompt for a short explanation to be typed for each key field
change (mostly <code>>State:</code> and
<code>>Responsible:</code>). This text is entered one line at
time, ending with <command>^D</command>.</para>
<para>This text is then sent via e-mail to the PR Submitter, the
Responsible developer, and <email>gnats-admin@NetBSD.org</email>.
It is also appended to the PR by <command>edit-pr</command> along
with the user ID of the developer making the change, a timestamp,
and the entered text.</para>
<para>Unfortunately, no external editor can be invoked at this
point; if you make a mistake, you'll have to use
<command>edit-pr</command> to correct it.</para>
</sect4>
</sect3>
<sect3 id="resolve">
<title>Resolving Problem Reports</title>
<sect4 id="ideal">
<title>The Ideal Process</title>
<para>In an ideal world, the process for a problem report is as
follows:</para>
<orderedlist>
<listitem>
<para>A NetBSD user has a problem with NetBSD. He invokes the
<command>send-pr</command> command on his system (assuming
it's still stable enough to do that), and files a Problem
Report. Hopefully, he follows all the advice found in <ulink
url="../Misc/pr-hints.html">"What goes into a Problem
Report."</ulink></para>
<para>If the user's own system is not stable enough to use
<command>send-pr</command>, there is a <ulink
url="../Misc/send-pr.html">web interface</ulink> that can be
used to submit problem reports.</para>
</listitem>
<listitem>
<para>When the PR arrives at <code>gnats.NetBSD.org</code>,
the GNATS database system examines it, and files it. If the
PR is malformed, it will be filed in the
<code>pending</code> category, marked confidential, awaiting
manual intervention by the GNATS database
administrator.</para>
<para>If the format is OK, the PR is assigned a PR number,
filed into the requested category, and E-mailed out again to
the default responsible party for the category, and to the
<ulink
url="../MailingLists/#netbsd-bugs">netbsd-bugs</ulink>
mailing list. A notice of the PR number and default
Responsible Person is also E-mailed back to the PR
Submitter.</para>
</listitem>
<listitem>
<para>The Responsible Person should read and analyze the
PR. Any other person who has insight into the problem should
also <ulink url="../Misc/send-pr.html#appending">add
whatever information they can to the problem report</ulink>
(this is why the report is mailed out to a mailing list; a
wide audience increases the probability that a key insight
needed to solve the problem will be discovered).</para>
<para>If the default Responsible Person determines that
another developer is a more appropriate Responsible Person,
the PR should be reassigned with
<command>edit-pr</command>. The new Responsible Person
should read and analyze the PR.</para>
</listitem>
<listitem>
<para>Once a cause and potential fix has been identified, a
description should be added to the PR, and the <ulink
url="../Misc/pr-states.html">state</ulink> should be changed
to <code>analyzed</code>. At this point, implementation of
the fix for the problem begins.</para>
<para>This part of the process should begin as quickly as
possible, since a user with a current problem is suffering,
but also has his attention engaged, and his hardware
available for testing potential fixes. If a PR is allowed to
languish, the opportunity to reproduce the problem and test
potential fixes may be lost.</para>
</listitem>
<listitem>
<para>Once the implementation of the fix is completed and communicated
to the PR submitter, the PR <ulink url="/Misc/pr-states.html">state</ulink>
should be changed to <code>feedback</code>, awaiting response from the PR
submitter that the fix really works.</para>
<para>A PR should also be put into <code>feedback</code> state when input
is required from the submitter to complete the analysis of the PR
(i.e. when you ask them a question), or when you need information
from some other source (essentially, <code>feedback</code> is a wait
state).</para>
</listitem>
<listitem>
<para>Once the PR submitter confirms that the fix works, the PR
can be <code>closed</code>.</para>
</listitem>
</orderedlist>
<para>At each step of the PR handling process, make sure that
feedback and other analysis and commentary is <ulink
url="../Misc/send-pr.html#appending">appended to the PR</ulink>
by using a proper E-mail subject line and making sure that the
messages are copied to
<email>gnats-bugs@NetBSD.org</email>. Having a complete record
of information about the PR is valuable both while hunting down
the bug and for future system maintenance.</para>
<para>If at all possible, it is important to get any fix committed
to the CVS trunk <ulink url="releng/pullups.html">pulled
up</ulink> by <ulink url="releng/">NetBSD Release
Engineering</ulink> to the "-release" branch, so that people who
are tracking that branch can get the fix right away rather than
waiting for the next major release of NetBSD. This also makes it
possible for the next point release of NetBSD to have the
fix.</para>
<para>The NetBSD Community is a whole lot of very smart, and very
experienced people. If you're having trouble analyzing a problem
report, ask questions in the appropriate <ulink
url="../MailingLists/">mailing list</ulink>; more than likely,
someone will be able to help.</para>
</sect4>
<sect4 id="otherways">
<title>Other Ways Things Get Done</title>
<para>The Ideal Process was described above. That's not the only way
that problem reports get handled. All of the principal people
involved in NetBSD are pretty busy, and can't devote full attention
to this project. As such, if you see a PR that you can solve that
hasn't been attended to yet, go claim it by setting yourself as the
Responsible Person with <command>edit-pr</command>, and solve
it.</para>
<para>Even if you don't feel qualified to hack the code yourself, if
you can offer a test case or other information, send it along to
GNATS to be <ulink url="../Misc/send-pr.html#appending">appended to
the PR</ulink>. <quote>Many hands make light work.</quote></para>
<para>Some problem reports are so trivial that the fix is obvious (or
perhaps the fix was provided by the submitter), that they go directly
from <code>open</code> to <code>closed</code> immediately after the fix is
committed.</para>
<para>If for some reason you find that you're unable to finish
handling the PR, reset the <code>>Responsible:</code> field to
whoever had responsibility before you took the PR over. Don't
prevent others from making progress on the PR because they think
you're taking care of it.</para>
<para>As long as you're marked as the Responsible Person for a PR,
you'll receive a monthly E-mail reminder about it. Use those
reminders to drive you to review PRs and put them into their correct
states as time passes.</para>
<para>When a PR is in <code>feedback</code> state, the PR submitter gets an
E-mail monthly reminder at the same time as the Responsible Persons
do, to prompt or prod them into responding. Generally, if there
has been no response for more than three months (three reminder
cycles), it's pretty safe to assume that the submitter is gone or
no longer cares. At that point, whether to close the PR becomes
a judgement call for the Responsible Person - how serious is it?
Should it be solved without further input from the Submitter?</para>
<para>The other way we use the GNATS PR database is to keep track of
problems which are waiting for larger issues to be solved. The
oldest PR in the database at this writing, <ulink
url="http://www.NetBSD.org/cgi-bin/query-pr-single.pl?number=13">lib/13</ulink>
(yes, of course it would be 13!) begs the entire
internationalization of the NetBSD system. I18N is a hard problem
that requires a wholesale overhaul of the system, which is why that
PR is still open after seven years. This doesn't mean we'll never
solve it; just that it isn't as critical as some other problems
reported in the database.</para>
<para>In effect, this usage of the GNATS PR database is as a long-term
project tracking system.</para>
</sect4>
</sect3>
<sect3 id="priorities">
<title> Priorities, Severities, and Releases</title>
<para>In an ideal world, the GNATS PR database would be empty, we'd
release perfect software, and Microsoft would be a shadow of its
current self.</para>
<para>The <code>>Priority:</code> field in the PR reflects this ideal,
in that <code>high</code> priority is supposed to be fixed immediately;
<code>medium</code> is supposed to be resolved before the next release
of NetBSD (major or minor?), and <code>low</code> priority gets solved
<quote>eventually</quote>.</para>
<para>In practice, PR resolution is dependent on the right mix of
submitter interest, developer interest, problem reproduceability,
hardware availability, and good timing. If any of the required
elements is missing from the mix, the PR will sit.</para>
<para>If we were really diligent about PRs, we would adjust the priority
of each PR to reflect its actual importance, and probability of
getting fixed according to the definitions. Unfortunately, that
requires an overall evaluation of Release Engineering goals and
targets and all PRs relative to each other, which is difficult for
a dispersed group to do in an organized fashion.</para>
<para>In contrast, the <code>>Severity:</code> field is really an
expression of the amount of pain the user is going through with the
problem being reported, and it's something we really shouldn't
adjust without careful consideration.</para>
<para>The proper procedure would be to review all PRs in the database
at each release point, to decide on a per-PR basis whether to
<quote>fix now</quote>, <quote>fix later</quote>,
<quote>suspend</quote> and adjust priorities. Perhaps one day we'll
have the resources and manpower for that.</para>
</sect3>
<sect3 id="remotegnats">
<title>Remote GNATS Operations</title>
<para>For people who find logging into a remote host tedious, the
following csh aliases might be useful:</para>
<programlisting>
alias query-pr 'ssh gnats.NetBSD.org query-pr --full \!* | tee pr-\!*'
alias edit-pr ssh -t gnats.NetBSD.org edit-pr
</programlisting>
</sect3>
</sect2>
</sect1>
<parentsec url="./" text="&os; Developer Documentation"/>
</webpage>
--k+w/mQv8wyuph6w0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: attachment; filename="PR.diff"
Index: Makefile
===================================================================
RCS file: /cvsroot/htdocs/developers/Makefile,v
retrieving revision 1.42
diff -u -r1.42 Makefile
--- Makefile 5 Apr 2007 14:42:00 -0000 1.42
+++ Makefile 5 Apr 2007 17:29:20 -0000
@@ -21,7 +21,7 @@
XMLDOCS+= style
XMLDOCS+= www
-LISTDOCS= PR.list
+XMLDOCS= PR
LISTDOCS+= translate-german.list translate-french.list
LISTDOCS+= translate-spanish.list
Index: layout.xml
===================================================================
RCS file: /cvsroot/htdocs/layout.xml,v
retrieving revision 1.231
diff -u -r1.231 layout.xml
--- layout.xml 4 Apr 2007 08:21:51 -0000 1.231
+++ layout.xml 5 Apr 2007 17:30:04 -0000
@@ -353,6 +357,7 @@
</tocentry>
<tocentry page="developers/de-lint.xml" filename="de-lint.html"/>
<tocentry page="developers/htdocs.xml" filename="htdocs.html"/>
+ <tocentry page="developers/PR.xml" filename="PR.html"/>
<tocentry page="developers/manpages.xml" filename="manpages.html"/>
<tocentry page="developers/mirrors.xml" filename="mirrors.html"/>
<tocentry page="developers/new-port.xml" filename="new-port.html"/>
--k+w/mQv8wyuph6w0--