Fix numerous style problems, remove many uses of "you" and "your"
(leaving only a few thousand), kinda sorta maybe remove some instances of passive voice, remove and reduce repeated redundancy, add some IDs to sections.
This commit is contained in:
Warren Block
parent
c4b1e609e0
commit
4aeb075af2
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=44225
1 changed files with 62 additions and 62 deletions
|
|
@ -46,7 +46,7 @@
|
|||
it.</para>
|
||||
|
||||
<para>This document attempts to describe how to write good problem
|
||||
reports. What, you ask, is a good problem report? Well, to go
|
||||
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>
|
||||
|
|
@ -56,37 +56,37 @@
|
|||
software projects.</para>
|
||||
|
||||
<para>Note that this article is organized thematically, not
|
||||
chronologically, so you should read through the entire document
|
||||
before submitting a problem report, rather than treat it as a
|
||||
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>
|
||||
<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 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 typographical error in a configuration file
|
||||
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 you and the
|
||||
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 do you determine what is a bug and what is not? As a
|
||||
simple rule of thumb your problem is <emphasis>not</emphasis> a
|
||||
<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. If you are looking
|
||||
for an answer, consider posing your question to the
|
||||
question rule covers a large majority of cases. When looking
|
||||
for an answer, consider posing the question to the
|
||||
&a.questions;.</para>
|
||||
|
||||
<para>Some cases where it may be appropriate to submit a problem
|
||||
|
|
@ -163,20 +163,20 @@
|
|||
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
|
||||
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 you should ascertain whether or not the problem is
|
||||
<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, you should first read
|
||||
<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
|
||||
|
|
@ -201,7 +201,7 @@
|
|||
<title>Preparations</title>
|
||||
|
||||
<para>A good rule to follow is to always do a background search
|
||||
before submitting a problem report. Maybe your problem has
|
||||
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
|
||||
|
|
@ -228,15 +228,15 @@
|
|||
<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 your
|
||||
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 you have overlooked.</para>
|
||||
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 your problem. You
|
||||
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>
|
||||
|
|
@ -245,19 +245,19 @@
|
|||
<listitem>
|
||||
<para>Next, the searchable
|
||||
<link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
|
||||
&os; PR database</link> (GNATS). Unless your problem
|
||||
&os; PR database</link> (GNATS). Unless the problem
|
||||
is recent or obscure, there is a fair chance it has already
|
||||
been reported.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Most importantly, you should attempt to see if existing
|
||||
<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 the
|
||||
<filename>/usr/src/UPDATING</filename> file on your system
|
||||
or its latest version at
|
||||
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
|
||||
|
|
@ -278,7 +278,7 @@
|
|||
</section>
|
||||
|
||||
<section xml:id="pr-writing">
|
||||
<title>Writing the problem report</title>
|
||||
<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
|
||||
|
|
@ -287,8 +287,8 @@
|
|||
tips and tricks to help make sure that your PR will be most
|
||||
effective.</para>
|
||||
|
||||
<section>
|
||||
<title>Tips and tricks for writing a good problem report</title>
|
||||
<section xml:id="pr-writing-tips">
|
||||
<title>Tips and Tricks for Writing a Good Problem Report</title>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
|
|
@ -351,7 +351,7 @@
|
|||
<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
|
||||
(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
|
||||
|
|
@ -506,52 +506,52 @@
|
|||
</itemizedlist>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Before you begin</title>
|
||||
<section xml:id="pr-writing-before-beginning">
|
||||
<title>Before Beginning</title>
|
||||
|
||||
<para>If you are using the &man.send-pr.1; program, make sure your
|
||||
<para>When using the &man.send-pr.1; program, make sure the
|
||||
<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.
|
||||
<para>Make sure that mail delivery is working.
|
||||
&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 are running &man.send-pr.1; on, your
|
||||
tracking of problem reports. If mail messages cannot be sent
|
||||
from the machine running &man.send-pr.1;, the
|
||||
problem report will not reach the GNATS database. For details
|
||||
on the setup of mail on &os;, see the <quote>Electronic
|
||||
Mail</quote> chapter of the &os; Handbook at
|
||||
<uri xlink:href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html">http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html</uri>.</para>
|
||||
|
||||
<para>Make sure that your mailer will not mangle the message on
|
||||
its way to GNATS. In particular, if your mailer automatically
|
||||
<para>Make sure that the mailer does not mangle the message on
|
||||
its way to GNATS. In particular, if the 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,
|
||||
characters, any patch will be rendered
|
||||
unusable. For the text sections, however, we request the
|
||||
insertion of 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
|
||||
<para>Similar considerations apply to use of the
|
||||
<link xlink:href="&url.base;/send-pr.html"> web-based
|
||||
PR submission form</link> instead of &man.send-pr.1;. Note that
|
||||
PR submission form</link>. 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 should
|
||||
to prepare your work offline so that nothing will be lost in
|
||||
case there is a problem submitting it. This can especially be a
|
||||
<para>Finally, if the submission is lengthy,
|
||||
prepare the work offline so that nothing will be lost if
|
||||
there is a problem submitting it. This can especially be a
|
||||
problem with the <link xlink:href="&url.base;/send-pr.html">web form</link>.</para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Attaching patches or files</title>
|
||||
<section xml:id="pr-writing-attaching-patches">
|
||||
<title>Attaching Patches or Files</title>
|
||||
|
||||
<para>The following applies to submitting PRs via email:</para>
|
||||
|
||||
<para>The &man.send-pr.1; program has provisions for attaching
|
||||
files to a problem report. You can attach as many files as
|
||||
you want provided that each has a unique base name (i.e. the
|
||||
you want provided that each has a unique base name (i.e., the
|
||||
name of the file proper, without the path). Just use the
|
||||
<option>-a</option> command-line option to specify the names
|
||||
of the files you wish to attach:</para>
|
||||
|
|
@ -561,8 +561,8 @@
|
|||
<para>Do not worry about binary files, they will be automatically
|
||||
encoded so as not to upset your mail agent.</para>
|
||||
|
||||
<para>If you attach a patch, make sure you use the
|
||||
<option>-c</option> or <option>-u</option> option to
|
||||
<para>When attaching a patch, be sure to use
|
||||
<option>-c</option> or <option>-u</option> with
|
||||
&man.diff.1; to create a context or unified diff (unified is
|
||||
preferred), and make
|
||||
sure to specify the exact SVN revision numbers of the files
|
||||
|
|
@ -605,13 +605,13 @@
|
|||
same terms as the original file you modified.</para>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Filling out the template</title>
|
||||
<section xml:id="pr-writing-filling-template">
|
||||
<title>Filling out the Template</title>
|
||||
|
||||
<para>The next section applies to the email method only:</para>
|
||||
|
||||
<para>When you run &man.send-pr.1;, you are presented with a
|
||||
template. The template consists of a list of fields, some of
|
||||
<para>&man.send-pr.1; presents a
|
||||
template consisting 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
|
||||
|
|
@ -871,7 +871,7 @@
|
|||
</note>
|
||||
|
||||
<example>
|
||||
<title>Correct use of arch-specific category</title>
|
||||
<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
|
||||
|
|
@ -880,7 +880,7 @@
|
|||
</example>
|
||||
|
||||
<example>
|
||||
<title>Incorrect use of arch-specific category</title>
|
||||
<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
|
||||
|
|
@ -1092,8 +1092,8 @@
|
|||
</itemizedlist>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<title>Sending off the problem report</title>
|
||||
<section xml:id="pr-writing-sending">
|
||||
<title>Sending the Problem Report</title>
|
||||
|
||||
<para>If you are using &man.send-pr.1;:</para>
|
||||
|
||||
|
|
@ -1141,7 +1141,7 @@
|
|||
<section xml:id="pr-followup">
|
||||
<title>Follow-up</title>
|
||||
|
||||
<para>Once your problem report has been filed, you will receive a
|
||||
<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
|
||||
|
|
@ -1161,7 +1161,7 @@
|
|||
<para>The easiest way is to use the followup link on
|
||||
the individual PR's web page, which you can reach from the
|
||||
<link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
|
||||
PR search page</link>. Clicking on this link will bring up an
|
||||
PR search page</link>. Clicking on this link will bring up
|
||||
an email window with the correct To: and Subject: lines filled in
|
||||
(if your browser is configured to do this).</para>
|
||||
</listitem>
|
||||
|
|
@ -1199,7 +1199,7 @@
|
|||
</section>
|
||||
|
||||
<section xml:id="pr-problems">
|
||||
<title>If you are having problems</title>
|
||||
<title>If There Are Problems</title>
|
||||
|
||||
<para>Most PRs go through the system and are accepted quickly;
|
||||
however, at times GNATS runs behind and you may not get your
|
||||
|
|
|
|||
Loading…
Reference in a new issue