Date: Sun, 10 Apr 2005 22:56:48 -0500 (CDT) From: Mark Linimon <linimon@lonesome.com> To: freebsd-doc@FreeBSD.org Subject: CFD: additions to the PR submission article Message-ID: <Pine.LNX.4.44.0504102250320.29887-100000@pancho>
next in thread | raw e-mail | index | archive | help
As part of my work on bugmeister I keep encountering the same problems
with PR submissions over and over. This proposed patch makes the
following changes:
- further clarifies the distinction between software written by
FreeBSD contributors and software written by others
- defines when code is too old to file a PR against
- adds text about mangled formatting, especially by mailers
Unless there are any objections I intend to commit these changes once
the freeze is lifted.
Thanks,
mcl
Index: article.sgml
===================================================================
RCS file: /home/FreeBSD/dcvs/doc/en_US.ISO8859-1/articles/problem-reports/article.sgml,v
retrieving revision 1.36
diff -u -r1.36 article.sgml
--- article.sgml 15 Jan 2005 02:16:42 -0000 1.36
+++ article.sgml 11 Apr 2005 03:53:25 -0000
@@ -104,20 +104,11 @@
<listitem>
<para>Notification of updates to externally maintained
- software (mainly ports, but also externally maintained base
- system components such as BIND or various GNU
- utilities).</para>
+ software (see below).</para>
</listitem>
</itemizedlist>
- <para>Another thing is that if the system on which you experienced
- the bug is not fairly up-to-date, you should seriously consider
- upgrading and trying to reproduce the problem on an up-to-date
- system before submitting a problem report. There are few things
- that will annoy a developer more than receiving a problem report
- about a bug she has already fixed.</para>
-
- <para>Finally, a bug that can not be reproduced can rarely be
+ <para>Note that a bug that can not 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
@@ -127,6 +118,71 @@
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 <application>bind</application>, &man.gcc.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. Usually these bugs will fall under either
+ the <literal>bin</literal> or <literal>gnu</literal>
+ categories.</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, you
+ should only report a problem to the &os; developers when you
+ believe the problem is &os;-specific; otherwise, you should
+ report it to the authors of the software.</para>
+ </listitem>
+
+ </itemizedlist>
+
+ <para>Then you should ascertain whether or not 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, you should first read
+ the FAQ section on
+ <ulink url="&url.books.faq;/introduction.html#LATEST-VERSION">
+ &os; versions</ulink>, 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
+ <ulink url="http://www.freebsd.org/security/">list of supported
+ versions</ulink>.
+
+ <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 id="pr-prep">
@@ -209,25 +265,6 @@
are also available via CVSweb.</para>
</listitem>
</itemizedlist>
-
- <para>Next, you need to make sure your problem report goes to the
- right people.</para>
-
- <para>The first catch here is that if the problem is a bug in
- third-party software (a port or a package you have installed), you
- should report the bug to the original author, not to the &os;
- Project. There are two exceptions to this rule: the first is if
- the bug does not occur on other platforms, in which case the
- problem may lie in how the software was ported to &os;; the
- second is if the original author has already fixed the bug and
- released a patch or a new version of his software, and the
- &os; port has not been updated yet.</para>
-
- <para>The second catch is that &os;'s bug tracking system sorts
- problem reports according to the category the originator
- selected. Therefore, if you select the wrong category when you
- submit your problem report, there is a good chance that it will
- go unnoticed for a while, until someone re-categorizes it.</para>
</section>
<section id="pr-writing">
@@ -434,7 +471,7 @@
<section>
<title>Before you begin</title>
- <para>Before running the &man.send-pr.1; program, make sure your
+ <para>If you are using the &man.send-pr.1; program, make sure your
<envar>VISUAL</envar> (or <envar>EDITOR</envar> if
<envar>VISUAL</envar> is not set) environment variable is set
to something sensible.</para>
@@ -447,6 +484,24 @@
on the setup of mail on &os;, see the <quote>Electronic
Mail</quote> chapter of the &os; Handbook at
<ulink url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html"></ulink>.</para>;
+
+ <para>Make sure that your mailer will not mangle the message on
+ its way to GNATS. In particular, if your mailer automatically
+ breaks lines, changes tabs to spaces, or escapes newline
+ characters, any patch that you submit will be rendered
+ unusable. For the text sections, however, we request that
+ you insert manual linebreaks somewhere around 70 characters,
+ so that the web display of the PR will be readable.</para>
+
+ <para>Similar considerations apply if you are using the web-based
+ PR submittal form instead of &man.send-pr.1;. Note that
+ cut-and-paste operations can have their own side-effects on
+ text formatting. In certain cases it may be necessary to use
+ &man.uuencode.1; to ensure that patches arrive unmodified.</para>
+
+ <para>Finally, if your submission will be lengthy, you may wish
+ to prepare your work offline so that nothing will be lost in
+ case there is a problem in transmission.</para>
</section>
<section>
@@ -492,7 +547,10 @@
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.</para>
+ 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 <literal>closed</literal>.</para>
<para>You should also take note that unless you explicitly
specify otherwise in your PR or in the patch itself, any
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?Pine.LNX.4.44.0504102250320.29887-100000>