os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Rewrite the section on what information needs to be supplied to make

Browse source 
a good Problem Report.  Add pointers to the new files ports/CHANGES
and ports/UPDATING.  Change some occurrences of FreeBSD to &os; if
they were in the affected lines (another commit will do the remaining
ones).  Suggest guidelines for the often-abused Severity and Priority
fields.  Add a pointer to the categories definition file.  Add the
'threads' category.  Add a warning to include the tracking number on
followups to save creating new, bogus, PRs.

PR:		docs/67062
Reviewed by:	ceri, keramida, others
Approved by:	ceri (mentor)
This commit is contained in:
Mark Linimon 2004-05-23 22:32:55 +00:00
parent c66aaf09db
commit 3cb0ed22ac
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=20985
1 changed files with 166 additions and 35 deletions

201
en_US.ISO8859-1/articles/problem-reports/article.sgml
View file

@ -5,6 +5,8 @@
%mailing-lists;
<!ENTITY % trademarks PUBLIC "-//FreeBSD//ENTITIES DocBook Trademark Entities//EN">
%trademarks;
<!ENTITY % freebsd PUBLIC "-//FreeBSD//ENTITIES DocBook Miscellaneous FreeBSD Entities//EN">
%freebsd;
]>
<article>
@ -125,8 +127,10 @@
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, and you should consider letting the
matter drop.</para>
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 &mdash; you should always try to rule
out these causes, whenever possible, before submitting a PR.</para>
</section>
<section id="pr-prep">
@ -185,14 +189,26 @@
</listitem>
<listitem>
<para>Finally, if you are upgrading from one version to
another&mdash;especially if you are upgrading to the
<literal>-current</literal> branch&mdash;you should
<para>Most importantly, you should 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 the
<filename>/usr/src/UPDATING</filename> file on your system
or its latest version at
<ulink URL="http://www.FreeBSD.org/cgi/cvsweb.cgi/src/UPDATING"></ulink>.
This file contains many pieces of vital information.</para>
(This is vital information
if you are upgrading from one version to
another&mdash;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).
<ulink URL="http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/UPDATING"></ulink> and
<ulink URL="http://www.FreeBSD.org/cgi/cvsweb.cgi/ports/CHANGES"></ulink> are also available via CVSweb.</para>
</listitem>
</itemizedlist>
@ -274,31 +290,102 @@
If you are maintaining a part of the source code (for
instance, a port), you might consider adding the string
<literal>[maintainer update]</literal> at the beginning of
your synopsis line and/or set the <quote>Class</quote> 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
with the <filename>Makefile</filename> of the PR every
time the PR is viewed to make sure this is an update sent
by the maintainer of the port.</para>
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.
You should include such things as what version you are
running (there is a place to put that, see below);
which architecture you are running on;
whether you are running from a release CDROM, or from
a system maintained by &man.cvsup.1; (and, if so, how
recently you updated); and, if a kernel problem,
if you have read <literal>src/UPDATING</literal>
(someone is guaranteed to ask). You do not necessarily
have to provide your kernel configuration, which ports
you have available, and a core dump (including these
by default only tends to fill up the database), but you
should be prepared to make them available, either
privately or publicly, if so asked.</para>
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 CDROM or download), or from
a system maintained by &man.cvsup.1; (and, if so, how
recently you updated). 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 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>a backtrace, if one was generated</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 <makevar>PORTSDIR</makevar></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>
</itemizedlist>
</listitem>
</itemizedlist>
</listitem>
<listitem>
@ -384,8 +471,9 @@
preferred), and make
sure to specify the exact CVS revision numbers of the files
you modified so the developers who read your report will be
able to apply them easily. A patch against the CURRENT or HEAD
CVS branch is preferred since all new code should be applied
able to apply them easily. For problems with the kernel or the
base utilities, a patch against &os.current; (the HEAD
CVS 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 STABLE
branch.</para>
@ -476,7 +564,7 @@
<para>As noted above, if your problem report includes a patch,
please have the synopsis start with <literal>[patch]</literal>;
if you are a maintainer, you may consider adding
<literal>[maintainer update]</literal> and/or set the
<literal>[maintainer update]</literal> and set the
<quote>Class</quote> of your PR to
<literal>maintainer-update</literal>.</para>
</listitem>
@ -488,20 +576,29 @@
<literal>critical</literal>. Do not overreact; refrain
from labeling your problem <literal>critical</literal>
unless it really is (e.g. <username>root</username> exploit, easily
reproducible panic). Developers tend to ignore this and
the next field, precisely because problem report
submitters tend to overrate their problems.</para>
reproducible panic) or <literal>serious</literal> unless
it is something that will affect many users (problems with
particular device drivers or system utilities). &os;
developers will not neccesarily work on your problem faster
if you inflate its importance since there are so many other
people who have done exactly that &mdash; in fact, some
developers pay little attention to this field, and the next,
because of this.</para>
</listitem>
<listitem>
<para><emphasis>Priority:</emphasis> One of
<literal>low</literal>, <literal>medium</literal> or
<literal>high</literal>. See above.</para>
<literal>high</literal>. <literal>high</literal> should
be reserved for problems that will affect practically
every user of &os; and <literal>medium</literal> for
something that will affect many users.</para>
</listitem>
<listitem>
<para><emphasis>Category:</emphasis> Choose one of the
following:</para>
following (taken from
<filename>/usr/gnats/gnats-adm/categories</filename>):</para>
<itemizedlist>
<listitem>
<para><literal>advocacy:</literal> problems relating to
@ -555,7 +652,7 @@
<listitem>
<para><literal>kern:</literal> problems with
kernel.</para>
the kernel or (non-platform-specific) device drivers.</para>
</listitem>
<listitem>
@ -584,6 +681,11 @@
issues.</para>
</listitem>
<listitem>
<para><literal>threads:</literal> problems related to the
&os; threads implementation (especially on &os.current;).</para>
</listitem>
<listitem>
<para><literal>www:</literal> Changes or enhancements to
the FreeBSD website.</para>
@ -712,11 +814,40 @@
<para>If someone requests additional information from you, or you
remember or discover something you did not mention in the
initial report, just mail it to
initial report, please use one of two methods to submit your
followup:</para>
<itemizedlist>
<listitem>
<para>The easiest way is to use the followup link on
the individual PR's web page, which you can reach from the
<ulink URL="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
PR search page</ulink>. Clicking on this link will bring up an
an email window with the correct To: and Subject: lines filled in
(if your browser is configured to do this).</para>
</listitem>
<listitem>
<para>Alternatively, you can just mail it to
<email>bug-followup@FreeBSD.org</email>, making sure that the
tracking number is included in the subject so the bug tracking
system will know what problem report to attach it to.</para>
<note>
<para>If you do <emphasis>not</emphasis> include the tracking
number, GNATS will become confused and create an entirely
new PR which it then assigns to the GNATS administrator,
and then your followup will become lost until someone
comes in to clean up the mess, which could be days or
weeks afterwards.</para>
<para>Wrong way: <programlisting>Subject: that PR I sent</programlisting>
Right way: <programlisting>Subject: Re: ports/12345: compilation problem with foo/bar</programlisting></para>
</note>
</listitem>
</itemizedlist>
<para>If the problem report remains open after the problem has
gone away, just send a follow-up (in the manner prescribed
above) saying that the problem report can be closed, and, if