- Update parts of this article and add a new "Tips and tricks for

writing a good problem report" section.
- Fix a few typos.
- Add a link to the searchable gnats database at FreeBSD.org.
- Point the users at /usr/src/UPDATING for more info before sending PRs.
- Be more verbose about patches and inline inclusion of diffs in a PR.
- Emphasize the importance of Class: maintainer-update and the use of
  "[maintainer update]"
- Describe what "[patch]" in synopsis lines means now that it's
  commonly used to help people who read PR indexes.

Submitted by:	Mark Linimon <linimon@lonesome.com>

en_US.ISO8859-1/articles/problem-reports/article.sgml

@@ -63,10 +63,10 @@
       engender a problem report.  Of course, nobody is perfect, and
       there will be times when you are convinced you have found a bug
       in a program when in fact you have misunderstood the syntax for
-      a command or made a typo in a configuration file (though that in
+      a command or made 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 not the right
+      where submitting a problem report is clearly <emphasis>not</emphasis> the right
       course of action, and will only serve to frustrate you and the
       developers.  Conversely, there are cases where it might be
       appropriate to submit a problem report about something else than
@@ -130,7 +130,17 @@
 
     <itemizedlist>
       <listitem>
-	<para>The FAQ.</para>
+	<para>The FreeBSD
+	  <ulink URL="../../books/faq/index.html">Frequently Asked
+	    Questions</ulink> (FAQ) list.
+	  The FAQ attempts to provide answers for a wide range of questions,
+	  such as those concerning
+	  <ulink URL="../../books/faq/hardware.html">hardware
+	    compatibility</ulink>,
+	  <ulink URL="../../books/faq/applications.html">user
+	    applications</ulink>,
+	  and <ulink URL="../../books/faq/kernelconfig.html">kernel
+	    configuration</ulink>.</para>
       </listitem>
 
       <listitem>
@@ -155,10 +165,23 @@
       </listitem>
 
       <listitem>
-	<para>Finally, the FreeBSD PR database.  Unless your problem
+	<para>Next, the searchable
+	  <ulink URL="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
+	  FreeBSD PR database</ulink> (GNATS).  Unless your problem
 	  is recent or obscure, there is a fair chance it has already
 	  been reported.</para>
       </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
+	  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>
+      </listitem>
     </itemizedlist>
 
     <para>Next, you need to make sure your problem report goes to the
@@ -187,10 +210,146 @@
 
     <para>Now that you have decided that your issue merits a problem
       report, and that it is a FreeBSD problem, it is time to write
-      the actual problem report.  Make sure your <envar>VISUAL</envar>
+      the actual problem report.  Before we get into the mechanics
-      (or <envar>EDITOR</envar> if <envar>VISUAL</envar> is not set)
+      of the program used to generate and submit PRs, here are some
-      environment variable is set to something sensible, and run
+      tips and tricks to help make sure that your PR will be most
-      &man.send-pr.1;.</para>
+      effective.</para>
+
+    <section>
+      <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 sysutils/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> 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> at the beginning of
+	    your synopsis line and/or 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>
+	</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>
+	</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
+	    <ulink URL="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"></ulink>.
+	    (Of course, everyone is guilty of forgetting to do this
+	    now and then.)</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 <ulink URL="http://www.FreeBSD.org/search/search.html#mailinglists"></ulink>
+	    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>
+      <title>Before you begin</title>
+
+      <para>Before running 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>
+
+      <para>You should also make sure that mail delivery works fine.
+	&man.send-pr.1; uses mail messages for the submission and
+	tracking of problem reports.  If you cannot post mail messages
+	from the machine you're running &man.send-pr.1; on, your
+	problem report will not reach the GNATS database.  For details
+	on the setup of mail on FreeBSD, see the <quote>Electronic
+	Mail</quote> chapter of the FreeBSD Handbook at
+	<ulink URL="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html"></ulink>.</para>
+    </section>
 
     <section>
       <title>Attaching patches or files</title>
@@ -209,18 +368,24 @@
 
       <para>If you attach a patch, make sure you use the
 	<option>-c</option> or <option>-u</option> option to
-	&man.diff.1; to create a context or unified diff, and make
+	&man.diff.1; to create a context or unified diff (unified is
+	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.</para>
 
-      <para>Note that while including small patches in a PR is
+      <para>If you attach a patch inline, instead of as an attachment,
-        generally all right, particularly when they fix the problem
+	note that the most common problem by far is the tendency of some
-        described in the PR, large patches and especially new code
+	email programs to render tabs as spaces, which will completely
+	ruin anything intended to be part of a Makefile.</para>
+
+      <para>Also note that while including small patches in a PR is
+	generally all right&mdash;particularly when they fix the problem
+	described in the PR&mdash;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, especially when Gnats is involved, and
+        tend to get mangled, especially when GNATS is involved, 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
@@ -235,8 +400,9 @@
     <section>
       <title>Filling out the template</title>
 
-      <para>The template consists of a list of fields, some of which
+      <para>When you run &man.send-pr.1;, you are presented with a
-	are pre-filled, and some of which have comments explaining
+	template.  The template consists of a list of fields, some of
+	which are pre-filled, and some of which have comments explaining
 	their purpose or listing acceptable values.  Do not worry
 	about the comments; they will be removed automatically if you
 	do not modify them or remove them yourself.</para>
@@ -263,7 +429,8 @@
 
 	<listitem>
 	  <para><emphasis>Originator:</emphasis> This is normally
-	    prefilled with the gecos field of the currently logged-in
+	    prefilled with the <literal>gecos</literal> field of the
+	    currently logged-in
 	    user.  Please specify your real name, optionally followed
 	    by your email address in angle brackets.</para>
 	</listitem>
@@ -276,7 +443,7 @@
 
 	<listitem>
 	  <para><emphasis>Confidential:</emphasis> This is prefilled
-	    to <literal>no</literal>, changing it makes no sense as
+	    to <literal>no</literal>.   Changing it makes no sense as
 	    there is no such thing as a confidential FreeBSD problem
 	    report&mdash;the PR database is distributed worldwide by
 	    <application>CVSup</application>.</para>
@@ -290,8 +457,12 @@
 	    summaries; problem reports with obscure synopses tend to
 	    get ignored.</para>
 
-	  <para>If your problem report includes a patch, please have
+	  <para>As noted above, if your problem report includes a patch,
-	    the synopsis start with <literal>[PATCH]</literal>.</para>
+	    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
+	    <quote>Class</quote> of your PR to
+	    <literal>maintainer-update</literal>.</para>
 	</listitem>
 
 	<listitem>
@@ -368,7 +539,8 @@
 
 	    <listitem>
 	      <para><literal>misc:</literal> anything that does not fit
-		in any of the other categories.</para>
+		in any of the other categories.  (Note that it is
+		easy for things to get lost in this category).</para>
 	    </listitem>
 
 	    <listitem>