Date: Sat, 22 May 2004 22:48:17 -0500 (CDT) From: Mark Linimon <linimon@lonesome.com> To: FreeBSD-gnats-submit@FreeBSD.org Subject: docs/67062: [patch] add more information to the Writing Problem Reports article Message-ID: <200405230348.i4N3mHks083829@lonesome.lonesome.com> Resent-Message-ID: <200405230400.i4N40gwk007678@freefall.freebsd.org>
next in thread | raw e-mail | index | archive | help
>Number: 67062
>Category: docs
>Synopsis: [patch] add more information to the Writing Problem Reports article
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: change-request
>Submitter-Id: current-users
>Arrival-Date: Sat May 22 21:00:42 PDT 2004
>Closed-Date:
>Last-Modified:
>Originator: Mark Linimon
>Release: FreeBSD 4.9-PRERELEASE i386
>Organization:
Lonesome Dove Computing Services
>Environment:
System: FreeBSD lonesome.lonesome.com 4.9-PRERELEASE FreeBSD 4.9-PRERELEASE #3: Thu Jan 22 20:41:05 CST 2004 root@lonesome.lonesome.com:/usr/src/sys/compile/MULTIMEDIA i386
>Description:
The Writing PRs article should be expanded to help eliminate
certain recurring meta-problems: PRs with insufficient information,
submitted incorrectly, or followed-up incorrectly.
>How-To-Repeat:
Read freebsd-current, freebsd-ports, or browse GNATS and try
not to tear your hair out :-)
>Fix:
Index: article.sgml
===================================================================
RCS file: /home/FreeBSD/dcvs/doc/en_US.ISO8859-1/articles/problem-reports/article.sgml,v
retrieving revision 1.28
diff -u -r1.28 article.sgml
--- article.sgml 24 Dec 2003 00:26:40 -0000 1.28
+++ article.sgml 23 May 2004 03:42:13 -0000
@@ -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 times
+ 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>
</section>
<section id="pr-prep">
@@ -185,14 +189,26 @@
</listitem>
<listitem>
- <para>Finally, if you are upgrading from one version to
- another—especially if you are upgrading to the
- <literal>-current</literal> branch—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—especially if you are upgrading to the
+ <literal>-current</literal> 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 possibly <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
+ -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
+ -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 will
+ instead respond that this just is not supported.</para>
+ </listitem>
+
+ <listitem>
+ <para>If a kernel problem, be prepared to supply the
+ following information, if asked to do so. (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 a ports problem, be prepared to supply the
+ following information, if asked to do so. (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,7 +471,8 @@
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
+ able to apply them easily. For problems with the kernel or the
+ base utilities, a patch against the CURRENT or 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
@@ -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 — 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 -CURRENT).</para>
+ </listitem>
+
<listitem>
<para><literal>www:</literal> Changes or enhancements to
the FreeBSD website.</para>
@@ -712,10 +814,39 @@
<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
>Release-Note:
>Audit-Trail:
>Unformatted:
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?200405230348.i4N3mHks083829>