84aa1e4310
PR: 194721 Differential Revision: https://reviews.freebsd.org/D2092 Submitted by: marino (original) Reviewed by: wblock, Andrew Berg (earlier version) Approved by: bcr (mentor) Sponsored by: ScaleEngine Inc.
1231 lines
47 KiB
XML
1231 lines
47 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
|
|
"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
|
|
<article xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
|
|
xml:lang="en">
|
|
|
|
<info>
|
|
<title>Writing &os; Problem Reports</title>
|
|
|
|
<legalnotice xml:id="trademarks" role="trademarks">
|
|
&tm-attrib.freebsd;
|
|
&tm-attrib.ibm;
|
|
&tm-attrib.intel;
|
|
&tm-attrib.sparc;
|
|
&tm-attrib.sun;
|
|
&tm-attrib.general;
|
|
</legalnotice>
|
|
|
|
<pubdate>$FreeBSD$</pubdate>
|
|
|
|
<releaseinfo>$FreeBSD$</releaseinfo>
|
|
|
|
<abstract>
|
|
<para>This article describes how to best formulate and submit a
|
|
problem report to the &os; Project.</para>
|
|
</abstract>
|
|
|
|
<authorgroup>
|
|
<author>
|
|
<personname>
|
|
<firstname>Dag-Erling</firstname>
|
|
<surname>Smørgrav</surname>
|
|
</personname>
|
|
<contrib>Contributed by </contrib>
|
|
</author>
|
|
|
|
<author>
|
|
<personname>
|
|
<firstname>Mark</firstname>
|
|
<surname>Linimon</surname>
|
|
</personname>
|
|
</author>
|
|
</authorgroup>
|
|
</info>
|
|
|
|
<indexterm><primary>problem reports</primary></indexterm>
|
|
|
|
<section xml:id="pr-intro">
|
|
<title>Introduction</title>
|
|
|
|
<para>One of the most frustrating experiences one can have as a
|
|
software user is to submit a problem report only to have it
|
|
summarily closed with a terse and unhelpful explanation like
|
|
<quote>not a bug</quote> or <quote>bogus PR</quote>. Similarly,
|
|
one of the most frustrating experiences as a software developer
|
|
is to be flooded with problem reports that are not really
|
|
problem reports but requests for support, or that contain little
|
|
or no information about what the problem is and how to reproduce
|
|
it.</para>
|
|
|
|
<para>This document attempts to describe how to write good problem
|
|
reports. What, one asks, is a good problem report? Well, to go
|
|
straight to the bottom line, a good problem report is one that
|
|
can be analyzed and dealt with swiftly, to the mutual
|
|
satisfaction of both user and developer.</para>
|
|
|
|
<para>Although the primary focus of this article is on &os;
|
|
problem reports, most of it should apply quite well to other
|
|
software projects.</para>
|
|
|
|
<para>Note that this article is organized thematically, not
|
|
chronologically. Read the entire document
|
|
before submitting a problem report, rather than treating it as a
|
|
step-by-step tutorial.</para>
|
|
</section>
|
|
|
|
<section xml:id="pr-when">
|
|
<title>When to Submit a Problem Report</title>
|
|
|
|
<para>There are many types of problems, and not all of them should
|
|
engender a problem report. Of course, nobody is perfect, and
|
|
there will be times when what seems to be a bug in a program is,
|
|
in fact, a misunderstanding of the syntax for a command or a
|
|
typographical error in a configuration file (though that in
|
|
itself may sometimes be indicative of poor documentation or poor
|
|
error handling in the application). There are still many cases
|
|
where submitting a problem report is clearly
|
|
<emphasis>not</emphasis> the right course of action, and will
|
|
only serve to frustrate both the submitter and the developers.
|
|
Conversely, there are cases where it might be appropriate to
|
|
submit a problem report about something else than a bug—an
|
|
enhancement or a new feature, for instance.</para>
|
|
|
|
<para>So how does one determine what is a bug and what is not? As
|
|
a simple rule of thumb, the problem is <emphasis>not</emphasis>
|
|
a bug if it can be expressed as a question (usually of the form
|
|
<quote>How do I do X?</quote> or <quote>Where can I find
|
|
Y?</quote>). It is not always quite so black and white, but the
|
|
question rule covers a large majority of cases. When looking
|
|
for an answer, consider posing the question to the
|
|
&a.questions;.</para>
|
|
|
|
<para>Consider these factors when submitting PRs about ports or
|
|
other software that is not part of &os; itself:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Please do not submit problem reports that simply state
|
|
that a newer version of an application is available. Ports
|
|
maintainers are automatically notified by
|
|
<application>portscout</application> when a new version of
|
|
an application becomes available. Actual patches to update
|
|
a port to the latest version are welcome.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>For unmaintained ports (<varname>MAINTAINER</varname>
|
|
is <literal>ports@FreeBSD.org</literal>),
|
|
a PR without an included patch is unlikely to get picked up
|
|
by a committer. To become the maintainer of an
|
|
unmaintained port, submit a PR with the request (patch
|
|
preferred but not required).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>In either case, following the process described in <link
|
|
xlink:href="&url.books.porters-handbook;/port-upgrading.html">Porter's
|
|
Handbook</link> will yield the best results. (You might
|
|
also wish to read <link
|
|
xlink:href="&url.articles.contributing-ports;/article.html">Contributing
|
|
to the FreeBSD Ports Collection</link>.)</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>A bug that cannot be reproduced can rarely be fixed. If the
|
|
bug only occurred once and you can not reproduce it, and it does
|
|
not seem to happen to anybody else, chances are none of the
|
|
developers will be able to reproduce it or figure out what is
|
|
wrong. That does not mean it did not happen, but it does mean
|
|
that the chances of your problem report ever leading to a bug
|
|
fix are very slim. To make matters worse, often these kinds of
|
|
bugs are actually caused by failing hard drives or overheating
|
|
processors — you should always try to rule out these
|
|
causes, whenever possible, before submitting a PR.</para>
|
|
|
|
<para>Next, to decide to whom you should file your problem report,
|
|
you need to understand that the software that makes up &os; is
|
|
composed of several different elements:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Code in the base system that is written and maintained
|
|
by &os; contributors, such as the kernel, the C library, and
|
|
the device drivers (categorized as <literal>kern</literal>);
|
|
the binary utilities (<literal>bin</literal>); the manual
|
|
pages and documentation (<literal>docs</literal>); and the
|
|
web pages (<literal>www</literal>). All bugs in these areas
|
|
should be reported to the &os; developers.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Code in the base system that is written and maintained
|
|
by others, and imported into &os; and adapted. Examples
|
|
include &man.clang.1;, and
|
|
&man.sendmail.8;. Most bugs in these areas should be
|
|
reported to the &os; developers; but in some cases they may
|
|
need to be reported to the original authors instead if the
|
|
problems are not &os;-specific.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Individual applications that are not in the base system
|
|
but are instead part of the &os; Ports Collection (category
|
|
<literal>ports</literal>). Most of these applications are
|
|
not written by &os; developers; what &os; provides is merely
|
|
a framework for installing the application. Therefore, only
|
|
report a problem to the &os; developers when the problem is
|
|
believed to be &os;-specific; otherwise, report it to the
|
|
authors of the software.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Then, ascertain whether the problem is timely. There are
|
|
few things that will annoy a developer more than receiving a
|
|
problem report about a bug she has already fixed.</para>
|
|
|
|
<para>If the problem is in the base system, first read the FAQ
|
|
section on <link
|
|
xlink:href="&url.books.faq;/introduction.html#LATEST-VERSION">&os;
|
|
versions</link>, if you are not already familiar with the
|
|
topic. It is not possible for &os; to fix problems in anything
|
|
other than certain recent branches of the base system, so filing
|
|
a bug report about an older version will probably only result in
|
|
a developer advising you to upgrade to a supported version to
|
|
see if the problem still recurs. The Security Officer team
|
|
maintains the
|
|
<link xlink:href="&url.base;/security/">list of supported
|
|
versions</link>.</para>
|
|
|
|
<para>If the problem is in a port, note that you must first
|
|
upgrade to the latest version of the Ports Collection and see if
|
|
the problem still applies. Due to the rapid pace of changes in
|
|
these applications, it is infeasible for &os; to support
|
|
anything other than the absolute latest versions, and problems
|
|
with older version of applications simply cannot be
|
|
fixed.</para>
|
|
</section>
|
|
|
|
<section xml:id="pr-prep">
|
|
<title>Preparations</title>
|
|
|
|
<para>A good rule to follow is to always do a background search
|
|
before submitting a problem report. Maybe the problem has
|
|
already been reported; maybe it is being discussed on the
|
|
mailing lists, or recently was; it may even already be fixed in
|
|
a newer version than what you are running. You should therefore
|
|
check all the obvious places before submitting your problem
|
|
report. For &os;, this means:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The &os; <link
|
|
xlink:href="&url.books.faq;/index.html">Frequently Asked
|
|
Questions</link> (FAQ) list.
|
|
The FAQ attempts to provide answers for a wide range of
|
|
questions, such as those concerning
|
|
<link xlink:href="&url.books.faq;/hardware.html">hardware
|
|
compatibility</link>,
|
|
<link xlink:href="&url.books.faq;/applications.html">user
|
|
applications</link>, and
|
|
<link xlink:href="&url.books.faq;/kernelconfig.html">kernel
|
|
configuration</link>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The <link
|
|
xlink:href="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">mailing
|
|
lists</link>—if you are not subscribed, use <link
|
|
xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">the
|
|
searchable archives</link> on the &os; web site. If the
|
|
problem has not been discussed on the lists, you might try
|
|
posting a message about it and waiting a few days to see if
|
|
someone can spot something that has been overlooked.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Optionally, the entire web—use your favorite
|
|
search engine to locate any references to the problem. You
|
|
may even get hits from archived mailing lists or newsgroups
|
|
you did not know of or had not thought to search
|
|
through.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Next, the searchable <link
|
|
xlink:href="https://bugs.freebsd.org/bugzilla/query.cgi">&os;
|
|
PR database</link> (Bugzilla). Unless the problem is recent
|
|
or obscure, there is a fair chance it has already been
|
|
reported.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Most importantly, attempt to see if existing
|
|
documentation in the source base addresses your
|
|
problem.</para>
|
|
|
|
<para>For the base &os; code, you should carefully study the
|
|
contents of <filename>/usr/src/UPDATING</filename> on your
|
|
system or the latest version at <uri
|
|
xlink:href="http://svnweb.freebsd.org/base/head/UPDATING?view=log">http://svnweb.freebsd.org/base/head/UPDATING?view=log</uri>.
|
|
(This is vital information if you are upgrading from one
|
|
version to another—especially if you are upgrading to
|
|
the &os.current; branch).</para>
|
|
|
|
<para>However, if the problem is in something that was
|
|
installed as a part of the &os; Ports Collection, you should
|
|
refer to <filename>/usr/ports/UPDATING</filename> (for
|
|
individual ports) or <filename>/usr/ports/CHANGES</filename>
|
|
(for changes that affect the entire Ports Collection). <uri
|
|
xlink:href="http://svnweb.freebsd.org/ports/head/UPDATING?view=log">http://svnweb.freebsd.org/ports/head/UPDATING?view=log</uri>
|
|
and <uri
|
|
xlink:href="http://svnweb.freebsd.org/ports/head/CHANGES?view=log">http://svnweb.freebsd.org/ports/head/CHANGES?view=log</uri>
|
|
are also available via svnweb.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section xml:id="pr-writing">
|
|
<title>Writing the Problem Report</title>
|
|
|
|
<para>Now that you have decided that your issue merits a problem
|
|
report, and that it is a &os; problem, it is time to write the
|
|
actual problem report. Before we get into the mechanics of the
|
|
program used to generate and submit PRs, here are some tips and
|
|
tricks to help make sure that your PR will be most
|
|
effective.</para>
|
|
|
|
<section xml:id="pr-writing-tips">
|
|
<title>Tips and Tricks for Writing a Good Problem Report</title>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>Do not leave the <quote>Synopsis</quote>
|
|
line empty.</emphasis> The PRs go both onto a mailing
|
|
list that goes all over the world (where the
|
|
<quote>Synopsis</quote> is used for the
|
|
<literal>Subject:</literal> line), but also into a
|
|
database. Anyone who comes along later and browses the
|
|
database by synopsis, and finds a PR with a blank subject
|
|
line, tends just to skip over it. Remember that PRs stay
|
|
in this database until they are closed by someone; an
|
|
anonymous one will usually just disappear in the
|
|
noise.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Avoid using a weak <quote>Synopsis</quote>
|
|
line.</emphasis> You should not assume that anyone
|
|
reading your PR has any context for your submission, so
|
|
the more you provide, the better. For instance, what part
|
|
of the system does the problem apply to? Do you only see
|
|
the problem while installing, or while running? To
|
|
illustrate, instead of
|
|
<literal>Synopsis: portupgrade is broken</literal>, see
|
|
how much more informative this seems:
|
|
<literal>Synopsis: port ports-mgmt/portupgrade coredumps
|
|
on -current</literal>. (In the case of ports, it is
|
|
especially helpful to have both the category and portname
|
|
in the <quote>Synopsis</quote> line.)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>If you have a patch, say so.</emphasis>
|
|
A PR with a patch included is much more likely to be
|
|
looked at than one without. If you are including one, put
|
|
the string <literal>[patch]</literal> (including the
|
|
brackets) at the beginning of the <quote>Synopsis</quote>.
|
|
(Although it is not mandatory to use that exact string, by
|
|
convention, that is the one that is used.)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>If you are a maintainer, say so.</emphasis>
|
|
If you are maintaining a part of the source code (for
|
|
instance, a port), you might consider adding the string
|
|
<literal>[maintainer update]</literal> (including the
|
|
brackets) at the beginning of your synopsis line, and you
|
|
definitely should set the <quote>Class</quote> of your PR
|
|
to <literal>maintainer-update</literal>. This way any
|
|
committer that handles your PR will not have to
|
|
check.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Be specific.</emphasis> The more information
|
|
you supply about what problem you are having, the better
|
|
your chance of getting a response.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Include the version of &os; you are running (there
|
|
is a place to put that, see below) and on which
|
|
architecture. You should include whether you are
|
|
running from a release (e.g., from a
|
|
<acronym>CD-ROM</acronym> or download), or from a
|
|
system maintained by Subversion (and, if so, what
|
|
revision number you are at). If you are tracking the
|
|
&os.current; branch, that is the very first thing
|
|
someone will ask, because fixes (especially for
|
|
high-profile problems) tend to get committed very
|
|
quickly, and &os.current; users are expected to keep
|
|
up.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Include which global options you have specified in
|
|
your <filename>make.conf</filename>. Note: specifying
|
|
<literal>-O2</literal> and above to &man.gcc.1; is
|
|
known to be buggy in many situations. While the &os;
|
|
developers will accept patches, they are generally
|
|
unwilling to investigate such issues due to simple
|
|
lack of time and volunteers, and may instead respond
|
|
that this just is not supported.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If the problem can be reproduced easily, include
|
|
information that will help a developer to reproduce it
|
|
themselves. If a problem can be demonstrated with
|
|
specific input then include an example of that input
|
|
if possible, and include both the actual and the
|
|
expected output. If this data is large or cannot be
|
|
made public, then do try to create a minimal file that
|
|
exhibits the same issue and that can be included
|
|
within the PR.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If this is a kernel problem, then be prepared to
|
|
supply the following information. (You do not have to
|
|
include these by default, which only tends to fill up
|
|
the database, but you should include excerpts that you
|
|
think might be relevant):</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>your kernel configuration (including which
|
|
hardware devices you have installed)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>whether or not you have debugging options
|
|
enabled (such as <literal>WITNESS</literal>), and
|
|
if so, whether the problem persists when you
|
|
change the sense of that option</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>the full text of any backtrace, panic or other
|
|
console output, or entries in
|
|
<filename>/var/log/messages</filename>, if any
|
|
were generated</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>the output of <command>pciconf -l</command>
|
|
and relevant parts of your
|
|
<command>dmesg</command> output if your problem
|
|
relates to a specific piece of hardware</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>the fact that you have read
|
|
<filename>src/UPDATING</filename> and that your
|
|
problem is not listed there (someone is guaranteed
|
|
to ask)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>whether or not you can run any other kernel as
|
|
a fallback (this is to rule out hardware-related
|
|
issues such as failing disks and overheating CPUs,
|
|
which can masquerade as kernel problems)</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If this is a ports problem, then be prepared to
|
|
supply the following information. (You do not
|
|
have to include these by default, which only tends to
|
|
fill up the database, but you should include excerpts
|
|
that you think might be relevant):</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>which ports you have installed</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>any environment variables that override the
|
|
defaults in <filename>bsd.port.mk</filename>, such
|
|
as <varname>PORTSDIR</varname></para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>the fact that you have read
|
|
<filename>ports/UPDATING</filename> and that your
|
|
problem is not listed there (someone is guaranteed
|
|
to ask)</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Avoid vague requests for
|
|
features.</emphasis> PRs of the form
|
|
<quote>someone should really implement something that does
|
|
so-and-so</quote> are less likely to get results than
|
|
very specific requests. Remember, the source is available
|
|
to everyone, so if you want a feature, the best way to
|
|
ensure it being included is to get to work! Also consider
|
|
the fact that many things like this would make a better
|
|
topic for discussion on
|
|
<literal>freebsd-questions</literal> than an entry in the
|
|
PR database, as discussed above.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Make sure no one else has already submitted
|
|
a similar PR.</emphasis> Although this has already been
|
|
mentioned above, it bears repeating here. It only take a
|
|
minute or two to use the web-based search engine at <uri
|
|
xlink:href="https://bugs.freebsd.org/bugzilla/query.cgi">https://bugs.freebsd.org/bugzilla/query.cgi</uri>.
|
|
(Of course, everyone is guilty of forgetting to do this
|
|
now and then.)</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Report only one issue per Problem
|
|
Report.</emphasis> Avoid including two or more problems
|
|
within the same report unless they are related. When
|
|
submitting patches, avoid adding multiple features or
|
|
fixing multiple bugs in the same PR unless they are
|
|
closely related—such PRs often take longer to
|
|
resolve.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Avoid controversial requests.</emphasis>
|
|
If your PR addresses an area that has been controversial
|
|
in the past, you should probably be prepared to not only
|
|
offer patches, but also justification for why the patches
|
|
are <quote>The Right Thing To Do</quote>. As noted above,
|
|
a careful search of the mailing lists using the archives
|
|
at <uri
|
|
xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">http://www.FreeBSD.org/search/search.html#mailinglists</uri>
|
|
is always good preparation.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Be polite.</emphasis> Almost anyone who
|
|
would potentially work on your PR is a volunteer. No one
|
|
likes to be told that they have to do something when they
|
|
are already doing it for some motivation other than
|
|
monetary gain. This is a good thing to keep in mind at
|
|
all times on Open Source projects.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section xml:id="pr-writing-before-beginning">
|
|
<title>Before Beginning</title>
|
|
|
|
<para>Similar considerations apply to use of the
|
|
<link xlink:href="https://bugs.freebsd.org/bugzilla/enter_bug.cgi"> web-based
|
|
PR submission form</link>. Be careful of cut-and-paste
|
|
operations that might change whitespace or other text
|
|
formatting.</para>
|
|
|
|
<para>Finally, if the submission is lengthy, prepare the work
|
|
offline so that nothing will be lost if there is a problem
|
|
submitting it.</para>
|
|
</section>
|
|
|
|
<section xml:id="pr-writing-attaching-patches">
|
|
<title>Attaching Patches or Files</title>
|
|
|
|
<para>When attaching a patch, be sure to use
|
|
<option>-u</option> with &man.diff.1;
|
|
to create or unified diff
|
|
and make sure to specify the exact SVN revision numbers of the
|
|
files you modified so the developers who read your report will
|
|
be able to apply them easily. For problems with the kernel or
|
|
the base utilities, a patch against &os.current; (the HEAD
|
|
Subversion branch) is preferred since all new code should be
|
|
applied and tested there first. After appropriate or
|
|
substantial testing has been done, the code will be
|
|
merged/migrated to the &os.stable; branch.</para>
|
|
|
|
<para>If you attach a patch inline, instead of as an attachment,
|
|
note that the most common problem by far is the tendency of
|
|
some email programs to render tabs as spaces, which will
|
|
completely ruin anything intended to be part of a
|
|
Makefile.</para>
|
|
|
|
<para>Do not send patches as attachments using
|
|
<command>Content-Transfer-Encoding:
|
|
quoted-printable</command>. These will perform character
|
|
escaping and the entire patch will be useless.</para>
|
|
|
|
<para>Also note that while including small patches in a PR is
|
|
generally all right—particularly when they fix the
|
|
problem described in the PR—large patches and especially
|
|
new code which may require substantial review before
|
|
committing should be placed on a web or ftp server, and the
|
|
URL should be included in the PR instead of the patch.
|
|
Patches in email tend to get mangled,
|
|
and the larger the patch, the harder it will be for
|
|
interested parties to unmangle it. Also, posting a patch on
|
|
the web allows you to modify it without having to resubmit the
|
|
entire patch in a followup to the original PR. Finally, large
|
|
patches simply increase the size of the database, since closed
|
|
PRs are not actually deleted but instead kept and simply
|
|
marked as complete.</para>
|
|
|
|
<para>You should also take note that unless you explicitly
|
|
specify otherwise in your PR or in the patch itself, any
|
|
patches you submit will be assumed to be licensed under the
|
|
same terms as the original file you modified.</para>
|
|
</section>
|
|
|
|
<section xml:id="pr-writing-filling-template">
|
|
<title>Filling out the Template</title>
|
|
|
|
<para>In the email template only, you will find the following
|
|
single-line fields:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>Submitter-Id:</emphasis> Do not change this.
|
|
The default value of <literal>current-users</literal> is
|
|
correct, even if you run &os.stable;.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Confidential:</emphasis> This is prefilled
|
|
to <literal>no</literal>. Changing it makes no sense as
|
|
there is no such thing as a confidential &os; problem
|
|
report—the PR database is distributed
|
|
worldwide.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Severity:</emphasis> One of
|
|
<literal>non-critical</literal>,
|
|
<literal>serious</literal> or <literal>critical</literal>.
|
|
Do not overreact; refrain from labeling your problem
|
|
<literal>critical</literal> unless it really is (e.g.,
|
|
data corruption issues, serious regression from previous
|
|
functionality in -CURRENT) or <literal>serious</literal>
|
|
unless it is something that will affect many users (kernel
|
|
panics or freezes; problems with particular device drivers
|
|
or system utilities). &os; developers will not
|
|
necessarily work on your problem faster if you inflate its
|
|
importance since there are so many other people who have
|
|
done exactly that — in fact, some developers pay
|
|
little attention to this field because of this.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Priority:</emphasis> This field indicates
|
|
how widespread the effects of this bug is likely to
|
|
be.</para>
|
|
</listitem>
|
|
|
|
|
|
</itemizedlist>
|
|
|
|
<para>The next section describes fields that are common to both
|
|
the email interface and the
|
|
<link xlink:href="https://bugs.freebsd.org/bugzilla/enter_bug.cgi">web
|
|
interface</link>:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>Originator:</emphasis> Please specify your
|
|
real name, optionally followed by your email address in
|
|
angle brackets. In the email interface, this is normally
|
|
prefilled with the <literal>gecos</literal> field of the
|
|
currently logged-in user.</para>
|
|
|
|
<note>
|
|
<para>The email address you use will become public
|
|
information and may become available to spammers. You
|
|
should either have spam handling procedures in place, or
|
|
use a temporary email account. However, please note
|
|
that if you do not use a valid email account at all, we
|
|
will not be able to ask you questions about your
|
|
PR.</para>
|
|
</note>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Organization:</emphasis> Whatever you feel
|
|
like. This field is not used for anything
|
|
significant.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Synopsis:</emphasis> Fill this out with a
|
|
short and accurate description of the problem. The
|
|
synopsis is used as the subject of the problem report
|
|
email, and is used in problem report listings and
|
|
summaries; problem reports with obscure synopses tend to
|
|
get ignored.</para>
|
|
|
|
<para>As noted above, if your problem report includes a
|
|
patch, please have the synopsis start with
|
|
<literal>[patch]</literal> (including the brackets); if
|
|
this is a ports PR and you are the maintainer, you may
|
|
consider adding <literal>[maintainer update]</literal>
|
|
(including the brackets) and set the <quote>Class</quote>
|
|
of your PR to <literal>maintainer-update</literal>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Category:</emphasis> Choose an appropriate
|
|
category.</para>
|
|
|
|
<para>The first thing you need to do is to decide what part
|
|
of the system your problem lies in. Remember, &os; is a
|
|
complete operating system, which installs both a kernel,
|
|
the standard libraries, many peripheral drivers, and a
|
|
large number of utilities (the
|
|
<quote>base system</quote>). However, there are thousands
|
|
of additional applications in the Ports Collection.
|
|
You'll first need to decide if the problem is in the base
|
|
system or something installed via the Ports
|
|
Collection.</para>
|
|
|
|
<para>Here is a description of the major categories:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>If a problem is with the kernel, the libraries
|
|
(such as standard C library <literal>libc</literal>),
|
|
or a peripheral driver in the base system, in general
|
|
you will use the <literal>kern</literal> category.
|
|
(There are a few exceptions; see below). In general
|
|
these are things that are described in section 2, 3,
|
|
or 4 of the manual pages.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If a problem is with a binary program such as
|
|
&man.sh.1; or &man.mount.8;, you will first need to
|
|
determine whether these programs are in the base
|
|
system or were added via the Ports Collection. If you
|
|
are unsure, you can do <command>whereis
|
|
<replaceable>programname</replaceable></command>.
|
|
&os;'s convention for the Ports Collection is to
|
|
install everything underneath
|
|
<filename class="directory">/usr/local</filename>,
|
|
although this can be overridden by a system
|
|
administrator. For these, you will use the
|
|
<literal>ports</literal> category (yes, even if the
|
|
port's category is <literal>www</literal>; see below).
|
|
If the location is
|
|
<filename class="directory">/bin</filename>,
|
|
<filename class="directory">/usr/bin</filename>,
|
|
<filename class="directory">/sbin</filename>, or
|
|
<filename class="directory">/usr/sbin</filename>, it
|
|
is part of the base system, and you should use the
|
|
<literal>bin</literal> category. (A few programs,
|
|
such as &man.gcc.1;, actually use the
|
|
<literal>gnu</literal> category, but do not worry
|
|
about that for now.) These are all things that are
|
|
described in section 1 or 8 of the manual
|
|
pages.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you believe that the error is in the startup
|
|
<literal>(rc)</literal> scripts, or in some kind of
|
|
other non-executable configuration file, then the
|
|
right category is <literal>conf</literal>
|
|
(configuration). These are things that are described
|
|
in section 5 of the manual pages.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you have found a problem in the documentation
|
|
set (articles, books, man pages), the correct choice
|
|
is <literal>docs</literal>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you are having a problem with the <link
|
|
xlink:href="http://www.FreeBSD.org">FreeBSD web
|
|
pages</link>, the proper choice is
|
|
<literal>www</literal>.</para>
|
|
|
|
<note>
|
|
<para>if you are having a problem with something from
|
|
a port named
|
|
<literal>www/<replaceable>someportname</replaceable></literal>,
|
|
this nevertheless goes in the
|
|
<literal>ports</literal> category.</para>
|
|
</note>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>There are a few more specialized categories.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>If the problem would otherwise be filed in
|
|
<literal>kern</literal> but has to do with the USB
|
|
subsystem, the correct choice is
|
|
<literal>usb</literal>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If the problem would otherwise be filed in
|
|
<literal>kern</literal> but has to do with the
|
|
threading libraries, the correct choice is
|
|
<literal>threads</literal>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If the problem would otherwise be in the base
|
|
system, but has to do with our adherence to standards
|
|
such as &posix;, the correct choice is
|
|
<literal>standards</literal>.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If the problem has to do with errors internal to a
|
|
&java.virtual.machine; (&jvm;), even though &java; was
|
|
installed from the Ports Collection, you should select
|
|
the <literal>java</literal> category. More general
|
|
problems with &java; ports still go under
|
|
<literal>ports</literal>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>This leaves everything else.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>If you are convinced that the problem will only
|
|
occur under the processor architecture you are using,
|
|
select one of the architecture-specific categories:
|
|
commonly <literal>i386</literal> for Intel-compatible
|
|
machines in 32-bit mode; <literal>amd64</literal> for
|
|
AMD machines running in 64-bit mode (this also
|
|
includes Intel-compatible machines running in EMT64
|
|
mode); and less commonly <literal>arm</literal>,
|
|
<literal>ia64</literal>, <literal>powerpc</literal>,
|
|
and <literal>sparc64</literal>.</para>
|
|
|
|
<note>
|
|
<para>These categories are quite often misused for
|
|
<quote>I do not know</quote> problems. Rather than
|
|
guessing, please just use
|
|
<literal>misc</literal>.</para>
|
|
</note>
|
|
|
|
<example>
|
|
<title>Correct Use of Arch-Specific Category</title>
|
|
|
|
<para>You have a common PC-based machine, and think
|
|
you have encountered a problem specific to a
|
|
particular chipset or a particular motherboard:
|
|
<literal>i386</literal> is the right
|
|
category.</para>
|
|
</example>
|
|
|
|
<example>
|
|
<title>Incorrect Use of Arch-Specific Category</title>
|
|
|
|
<para>You are having a problem with an add-in
|
|
peripheral card on a commonly seen bus, or a problem
|
|
with a particular type of hard disk drive: in this
|
|
case, it probably applies to more than one
|
|
architecture, and <literal>kern</literal> is the
|
|
right category.</para>
|
|
</example>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>If you really do not know where the problem lies
|
|
(or the explanation does not seem to fit into the ones
|
|
above), use the <literal>misc</literal> category.
|
|
Before you do so, you may wish to ask for help on the
|
|
&a.questions; first. You may be advised that one of
|
|
the existing categories really is a better
|
|
choice.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Here is the current list of categories (taken from
|
|
<uri
|
|
xlink:href="http://svnweb.freebsd.org/base/head/gnu/usr.bin/send-pr/categories">http://svnweb.freebsd.org/base/head/gnu/usr.bin/send-pr/categories</uri>):</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><literal>advocacy:</literal> problems relating to
|
|
&os;'s public image. Obsolete.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>amd64:</literal> problems specific to the
|
|
AMD64 platform.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>arm:</literal> problems specific to the
|
|
ARM platform.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>bin:</literal> problems with userland
|
|
programs in the base system.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>conf:</literal> problems with
|
|
configuration files, default values, and so
|
|
forth.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>docs:</literal> problems with manual
|
|
pages or on-line documentation.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>gnu:</literal> problems with imported GNU
|
|
software such as &man.gcc.1; or &man.grep.1;.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>i386:</literal> problems specific to the
|
|
&i386; platform.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>ia64:</literal> problems specific to the
|
|
ia64 platform.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>java:</literal> problems related to the
|
|
&java; Virtual Machine.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>kern:</literal> problems with
|
|
the kernel, (non-platform-specific) device drivers,
|
|
or the base libraries.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>misc:</literal> anything that does not
|
|
fit in any of the other categories. (Note that there
|
|
is almost nothing that truly belongs in this category,
|
|
except for problems with the release and build
|
|
infrastructure. Temporary build failures on
|
|
<literal>HEAD</literal> do not belong here. Also note
|
|
that it is easy for things to get lost in this
|
|
category).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>ports:</literal> problems relating to the
|
|
Ports Collection.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>powerpc:</literal> problems specific to
|
|
the &powerpc; platform.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>sparc64:</literal> problems specific to
|
|
the &sparc64; platform.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>standards:</literal> Standards
|
|
conformance issues.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>threads:</literal> problems related to
|
|
the &os; threads implementation (especially on
|
|
&os.current;).</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>usb:</literal> problems related to the
|
|
&os; USB implementation.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>www:</literal> Changes or enhancements to
|
|
the &os; website.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Class:</emphasis> Choose one of the
|
|
following:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><literal>sw-bug:</literal> software bugs.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>doc-bug:</literal> errors in
|
|
documentation.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>change-request:</literal> requests for
|
|
additional features or changes in existing
|
|
features.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>update:</literal> updates to ports or
|
|
other contributed software.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><literal>maintainer-update:</literal> updates to
|
|
ports for which you are the maintainer.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Release:</emphasis> The version of &os;
|
|
that you are running. This is filled out automatically if
|
|
you are using &man.send-pr.1; and need only be changed if
|
|
you are sending a problem report from a different system
|
|
than the one that exhibits the problem.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Finally, there is a series of multi-line fields:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para><emphasis>Environment:</emphasis> This should
|
|
describe, as accurately as possible, the environment in
|
|
which the problem has been observed. This includes the
|
|
operating system version, the version of the specific
|
|
program or file that contains the problem, and any other
|
|
relevant items such as system configuration, other
|
|
installed software that influences the problem,
|
|
etc.—quite simply everything a developer needs to
|
|
know to reconstruct the environment in which the problem
|
|
occurs.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Description:</emphasis> A complete and
|
|
accurate description of the problem you are experiencing.
|
|
Try to avoid speculating about the causes of the problem
|
|
unless you are certain that you are on the right track, as
|
|
it may mislead a developer into making incorrect
|
|
assumptions about the problem.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>How-To-Repeat:</emphasis> A summary of the
|
|
actions you need to take to reproduce the problem.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><emphasis>Fix:</emphasis> Preferably a patch, or at
|
|
least a workaround (which not only helps other people with
|
|
the same problem work around it, but may also help a
|
|
developer understand the cause for the problem), but if
|
|
you do not have any firm ideas for either, it is better to
|
|
leave this field blank than to speculate.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section xml:id="pr-writing-sending">
|
|
<title>Sending the Problem Report</title>
|
|
|
|
<para>If you are using &man.send-pr.1;:</para>
|
|
|
|
<para>Once you are done filling out the template, have saved it,
|
|
and exit your editor, &man.send-pr.1; will prompt you with
|
|
<prompt>s)end, e)dit or a)bort?</prompt>. You can then hit
|
|
<userinput>s</userinput> to go ahead and submit the problem
|
|
report, <userinput>e</userinput> to restart the editor and
|
|
make further modifications, or <userinput>a</userinput> to
|
|
abort. If you choose the latter, your problem report will
|
|
remain on disk (&man.send-pr.1; will tell you the filename
|
|
before it terminates), so you can edit it at your leisure, or
|
|
maybe transfer it to a system with better net connectivity,
|
|
before sending it with the <option>-f</option> to
|
|
&man.send-pr.1;:</para>
|
|
|
|
<screen>&prompt.user; <userinput>send-pr -f ~/my-problem-report</userinput></screen>
|
|
|
|
<para>This will read the specified file, validate the contents,
|
|
strip comments and send it off.</para>
|
|
|
|
<para>If you are using the <link
|
|
xlink:href="https://bugs.freebsd.org/bugzilla/enter_bug.cgi">web form</link>:</para>
|
|
|
|
<para>Before you hit <literal>submit</literal>, you will need to
|
|
fill in a field containing text that is represented in image
|
|
form on the page. This unfortunate measure has had to be
|
|
adopted due to misuse by automated systems and a few misguided
|
|
individuals. It is a necessary evil that no one likes; please
|
|
do not ask us to remove it.</para>
|
|
|
|
<para>Note that you are <literal>strongly advised</literal> to
|
|
save your work somewhere before hitting
|
|
<literal>submit</literal>. A common problem for users is to
|
|
have their web browser displaying a stale image from its
|
|
cache. If this happens to you, your submission will be
|
|
rejected and you may lose your work.</para>
|
|
|
|
<para>If you are unable to view images for any reason, and are
|
|
also unable to use &man.send-pr.1;, please accept our
|
|
apologies for the inconvenience and email your problem report
|
|
to the bugbuster team at
|
|
<email>freebsd-bugbusters@FreeBSD.org</email>.</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section xml:id="pr-followup">
|
|
<title>Follow-up</title>
|
|
|
|
<para>Once the problem report has been filed, you will receive a
|
|
confirmation by email which will include the tracking number
|
|
that was assigned to your problem report and a URL you can use
|
|
to check its status. With a little luck, someone will take an
|
|
interest in your problem and try to address it, or, as the case
|
|
may be, explain why it is not a problem. You will be
|
|
automatically notified of any change of status, and you will
|
|
receive copies of any comments or patches someone may attach to
|
|
your problem report's audit trail.</para>
|
|
|
|
<para>If someone requests additional information from you, or you
|
|
remember or discover something you did not mention in the
|
|
initial report, please submit a follow up. The number one
|
|
reason for a bug not getting fixed is lack of communication with
|
|
the originator.</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>The easiest way is to use the comment option on the
|
|
individual PR's web page, which you can reach from the <link
|
|
xlink:href="https://bugs.freebsd.org/bugzilla/query.cgi">PR
|
|
search page</link>.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>If the problem report remains open after the problem has
|
|
gone away, just add a comment
|
|
saying that the problem report can be closed, and, if
|
|
possible, explaining how or when the problem was fixed.</para>
|
|
|
|
<para>Sometimes there is a delay of a week or two where the
|
|
problem report remains untouched, not assigned or commented on
|
|
by anyone. This can happen when there is an increased problem
|
|
report backlog or during a holiday season. When a problem
|
|
report has not received attention after several weeks, it is
|
|
worth finding a committer particularly interested in working on
|
|
it.</para>
|
|
|
|
<para>There are a few ways to do so, ideally in the following
|
|
order, with a few days between attempting each communication
|
|
channel:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>Find the relevant &os; mailing list for the problem
|
|
report from the <link
|
|
xlink:href="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">list
|
|
in the Handbook</link> and send a message to that list
|
|
asking about assistance or comments on the problem
|
|
report.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Join the relevant <acronym>IRC</acronym> channels.
|
|
A partial listing is here: <link
|
|
xlink:href="https://wiki.freebsd.org/IrcChannels"></link>.
|
|
Inform the people in that channel about the problem report
|
|
and ask for assistance. Be patient and stay in the channel
|
|
after posting, so that the people from different time zones
|
|
around the world have a chance to catch up.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Find committers interested in the problem that was
|
|
reported. If the problem was in a particular tool, binary,
|
|
port, document, or source file, check the <link
|
|
xlink:href="http://svnweb.FreeBSD.org">SVN
|
|
Repository</link>. Locate the last few committers who
|
|
made substantive changes to the file, and try to reach them
|
|
via <acronym>IRC</acronym> or email. A list of committers
|
|
and their emails can be found in the <link
|
|
xlink:href="&url.articles.contributors.en;">Contributors
|
|
to &os;</link> article.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>Remember that these people are volunteers, just like
|
|
maintainers and users, so they might not be immediately
|
|
available to assist with the problem report. Patience and
|
|
consistency in the follow-ups is highly advised and appreciated.
|
|
With enough care and effort dedicated to that follow-up process,
|
|
finding a committer to take care of the problem report is just a
|
|
matter of time.</para>
|
|
</section>
|
|
|
|
<section xml:id="pr-problems">
|
|
<title>If There Are Problems</title>
|
|
|
|
<para>If you found an issue with the bug system, file a bug!
|
|
There is a category for exactly this purpose. If you are unable
|
|
to do so, contact the bug wranglers at
|
|
<email>bugmeister@FreeBSD.org</email>.</para>
|
|
</section>
|
|
|
|
<section xml:id="pr-further">
|
|
<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><link
|
|
xlink:href="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">How
|
|
to Report Bugs Effectively</link>—an excellent essay
|
|
by Simon G. Tatham on composing useful (non-&os;-specific)
|
|
problem reports.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para><link
|
|
xlink:href="&url.articles.pr-guidelines;/article.html">Problem
|
|
Report Handling Guidelines</link>—valuable insight
|
|
into how problem reports are handled by the &os;
|
|
developers.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<index/>
|
|
</article>
|