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

More typo and markup fixes.

Browse source 
Submitted by:	keramidas.
This commit is contained in:
Dag-Erling Smørgrav 2001-11-23 15:47:17 +00:00
parent b99127fbd4
commit 247e04f88c
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=11278
1 changed files with 91 additions and 91 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -38,11 +38,12 @@ FreeBSD Entities//EN"> %freebsd;
<para>One of the most frustrating experiences one can have as a
software user is to submit a problem report only to have it
summarily closed with a terse and unhelpful explanation like
"not a bug" or "bogus PR". Similarly, one of the most
frustrating experiences as a software developer is to be flooded
with problem reports that are not really problem reports but
requests for support, or that contain little or no information
about what the problem is and how to reproduce it.</para>
<quote>not a bug</quote> or <quote>bogus PR</quote>. Similarly,
one of the most frustrating experiences as a software developer
is to be flooded with problem reports that are not really
problem reports but requests for support, or that contain little
or no information about what the problem is and how to reproduce
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
@ -56,8 +57,8 @@ FreeBSD Entities//EN"> %freebsd;
<para>Note that this article is organized thematically, not
chronologically, so you should read through the entire document
before submitting a PR, rather than treat it as a step-by-step
tutorial.</para>
before submitting a problem report, rather than treat it as a
step-by-step tutorial.</para>
</sect1>
<sect1 id="pr-when">
@ -65,31 +66,31 @@ FreeBSD Entities//EN"> %freebsd;
<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've found a bug in
a program when in fact you've misunderstood the syntax for a
command or made a typo in a configuration file (though that in
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
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
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
a bug &mdash; an enhancement or a feature request, for
a bug&mdash;an enhancement or a feature request, for
instance.</para>
<para>So how do you determine what's a bug and what is not? As a
<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
bug if it can be expressed as a question (usually of the form
"How do I do X?" or "Where can I find Y?"). It's not always
quite so black and white, but the question rule covers a large
majority of cases.</para>
<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.</para>
<para>Some cases where it may be appropriate to submit a problem
report about something that is not a bug are:</para>
<itemizedlist>
<listitem>
<para>Requests for feature enhancments. It is generally a
<para>Requests for feature enhancements. It is generally a
good idea to air these on the mailing lists before
submitting a problem report.</para>
</listitem>
@ -109,14 +110,14 @@ FreeBSD Entities//EN"> %freebsd;
that will annoy a developer more than receiving a problem report
about a bug she's already fixed.</para>
<para>Finally, a bug that can't be reproduced can rarely be fixed.
If the bug only occurred once and you can't reproduce it, and it
doesn't seem to happen to anybody else, chances are none of the
developers will be able to reproduce it or figure out what's
wrong. That doesn't mean it didn't 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>
<para>Finally, 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
out what's 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>
</sect1>
<sect1 id="pr-prep">
@ -124,11 +125,11 @@ FreeBSD Entities//EN"> %freebsd;
<para>A good rule to follow is to always do a background search
before submitting a problem report. Maybe your problem has
already been reported; maybe it's being discussed on the mailing
lists, or recently was; it may even already be fixed in a newer
version than what you're running. You should therefore check
all the obvious places before submitting your PR. For FreeBSD,
this means:</para>
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
check all the obvious places before submitting your problem
report. For FreeBSD, this means:</para>
<itemizedlist>
<listitem>
@ -136,24 +137,24 @@ FreeBSD Entities//EN"> %freebsd;
</listitem>
<listitem>
<para>The mailing lists &mdash; if you're not subscribed, use
<para>The mailing lists&mdash;if you're not subscribed, use
the searchable archives on the FreeBSD web site. If your
problem hasn't been discussed on the lists, you might try
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've overlooked.</para>
someone can spot something you have overlooked.</para>
</listitem>
<listitem>
<para>Optionally, the entire web &mdash; use your favorite
<para>Optionally, the entire web&mdash;use your favorite
search engine to locate any references to your problem. You
may even get hits from archived mailing lists or newsgroups
you didn't know of or hadn't thought to search
you did not know of or had not thought to search
through.</para>
</listitem>
<listitem>
<para>Finally, the FreeBSD PR database. Unless your problem
is recent or obscure, there's a fair chance it's already
is recent or obscure, there is a fair chance it has already
been reported.</para>
</listitem>
</itemizedlist>
@ -169,12 +170,12 @@ FreeBSD Entities//EN"> %freebsd;
problem may lie in how the software was ported to FreeBSD; 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
FreeBSD port hasn't been updated yet.</para>
FreeBSD port has not been updated yet.</para>
<para>The second catch is that FreeBSD'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's a good chance that it will
submit your problem report, there is a good chance that it will
go unnoticed for a while, until someone re-categorizes
it.</para>
</sect1>
@ -182,10 +183,10 @@ FreeBSD Entities//EN"> %freebsd;
<sect1 id="pr-writing">
<title>Writing the problem report</title>
<para>Now that you've decided that your issue merits a problem
report, and that it's a FreeBSD problem, it's time to write the
actual PR. Make sure your <envar>VISUAL</envar> (or
<envar>EDITOR</envar> if <envar>VISUAL</envar> is not set)
<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>
(or <envar>EDITOR</envar> if <envar>VISUAL</envar> is not set)
environment variable is set to something sensible, and run
&man.send-pr.1;.</para>
@ -198,13 +199,13 @@ FreeBSD Entities//EN"> %freebsd;
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>
<screen>&prompt.user; <userinput>send-pr -a /var/run/dmesg -a /tmp/errors</userinput>
</screen>
<para>Don't 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
&man.diff.1; to create a context or unified diff, and make
@ -218,15 +219,15 @@ FreeBSD Entities//EN"> %freebsd;
<para>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. Don't worry about
the comments; they'll be removed automatically if you don't
modify them or remove them yourself.</para>
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>
<para>At the top of the template, below the
<literal>SEND-PR:</literal> lines, are the email headers. You
don't normally need to modify these, unless you're sending the
PR from a machine or account that can send but not receive
mail, in which case you'll want to set the
do not normally need to modify these, unless you are sending
the problem report from a machine or account that can send but
not receive mail, in which case you will want to set the
<literal>From:</literal> and <literal>Reply-To:</literal> to
your real email address. You may also want to send yourself
(or someone else) a carbon copy of the problem report by
@ -258,17 +259,18 @@ FreeBSD Entities//EN"> %freebsd;
<listitem>
<para><emphasis>Confidential:</emphasis> This is prefilled
to <literal>no</literal>; changing it makes no sense as
there is no such thing as a confidential FreeBSD PR
&mdash; the PR database is distributed worldwide by
there is no such thing as a confidential FreeBSD problem
report&mdash;the PR database is distributed worldwide by
CVSup.</para>
</listitem>
<listitem>
<para><emphasis>Synopsis:</emphasis> Fill this out with a
short and accurate description of the problem. The
synopsis is used as the subject of the PR email, and is
used in PR listings and summaries; problem reports with
obscure synopses tend to get ignored.</para>
synopsis is used as the subject of the problem report
email, and is used in problem report listings and
summaries; problem reports with obscure synopses tend to
get ignored.</para>
<para>If your problem report includes a patch, please have
the synopsis start with <literal>[PATCH]</literal>.</para>
@ -278,12 +280,12 @@ FreeBSD Entities//EN"> %freebsd;
<para><emphasis>Severity:</emphasis> One of
<literal>non-critical</literal>,
<literal>serious</literal> or
<literal>critical</literal>. Don't overreact; refrain
<literal>critical</literal>. Do not overreact; refrain
from labeling your problem <literal>critical</literal>
unless it really is (e.g. root exploit, easily
reproducible panic). Developers tend to ignore this and
the next field, precisely because PR submitters tend to
overrate their problems.</para>
the next field, precisely because problem report
submitters tend to overrate their problems.</para>
</listitem>
<listitem>
@ -291,7 +293,7 @@ FreeBSD Entities//EN"> %freebsd;
<literal>low</literal>, <literal>medium</literal> or
<literal>high</literal>. See above.</para>
</listitem>
<listitem>
<para><emphasis>Category:</emphasis> Choose one of the
following:</para>
@ -337,7 +339,7 @@ FreeBSD Entities//EN"> %freebsd;
</listitem>
<listitem>
<para><literal>misc:</literal> anything that doesn't fit
<para><literal>misc:</literal> anything that does not fit
in any of the other categories.</para>
</listitem>
@ -384,13 +386,13 @@ FreeBSD Entities//EN"> %freebsd;
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para><emphasis>Release:</emphasis> The version of FreeBSD
that you are running. This is filled out automatically by
&man.send-pr.1; and need only be changed if you are
sending a PR from a different system than the one that
exhibits the problem.</para>
sending a problem report from a different system than the
one that exhibits the problem.</para>
</listitem>
</itemizedlist>
@ -404,12 +406,12 @@ FreeBSD Entities//EN"> %freebsd;
operating system version, the version of the specific
program or file that contains the problem, and any other
relevant items such as system configuration, other
installed software that influences the problem, etc.
&mdash; quite simply everything a developer needs to know
to reconstruct the environment in which the problem
installed software that influences the problem,
etc.&mdash;quite simply everything a developer needs to
know to reconstruct the environment in which the problem
occurs.</para>
</listitem>
<listitem>
<para><emphasis>Description:</emphasis> A complete and
accurate description of the problem you are experiencing.
@ -418,30 +420,30 @@ FreeBSD Entities//EN"> %freebsd;
it may mislead a developer into making incorrect
assumptions about the problem.</para>
</listitem>
<listitem>
<para><emphasis>How-To-Repeat:</emphasis> A summary of the
actions you need to take to reproduce the problem.</para>
</listitem>
<listitem>
<para><emphasis>Fix:</emphasis> Preferably a patch, or at
least a workaround (which not only helps other people with
the same problem work around it, but may also help a
developer understand the cause for the problem), but if
you don't have any firm ideas for either, it's better to
you do not have any firm ideas for either, it's better to
leave this field blank than to speculate.</para>
</listitem>
</itemizedlist>
</sect2>
<sect2>
<title>Sending off the PR</title>
<title>Sending off the problem report</title>
<para>Once you're done filling out the template, have saved it,
<para>Once you are done filling out the template, have saved it,
and exit your editor, &man.send-pr.1; will prompt you with
<prompt>s)end, e)dit or a)bort?</prompt>. You can then hit
<userinput>s</userinput> to go ahead and submit the PR,
<userinput>s</userinput> to go ahead and submit the problem report,
<userinput>e</userinput> to restart the editor and make
further modifications, or <userinput>a</userinput> to abort.
If you choose the latter, your problem report will remain on
@ -450,9 +452,8 @@ FreeBSD Entities//EN"> %freebsd;
transfer it to a system with better net connectivity, before
sending it with the <option>-f</option> to
&man.send-pr.1;:</para>
<screen>&prompt.user; <userinput>send-pr -f ~/my-problem-report</userinput>
</screen>
<screen>&prompt.user; <userinput>send-pr -f ~/my-problem-report</userinput></screen>
<para>This will read the specified file, validate the contents,
strip comments and send it off.</para>
@ -463,27 +464,26 @@ FreeBSD Entities//EN"> %freebsd;
<sect1 id="pr-followup">
<title>Follow-up</title>
<para>Once your problem report has been filed, you'll receive a
<para>Once your problem report has been filed, you will receive a
confirmation by email which will include the tracking number
that was assigned to your PR and a URL you can use to check its
status. With a little luck, someone will take an interest in
your problem and try to address it, or, as the case may be,
explain why it's not a problem. You'll be automatically
notified of any change of status, and you'll receive copies of
any comments or patches someone may attach to your PR's audit
trail.</para>
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
interest in your problem and try to address it, or, as the case
may be, explain why it is not a problem. You will be
automatically notified of any change of status, and you will
receive copies of any comments or patches someone may attach to
your problem report's audit trail.</para>
<para>If someone requests additional information from you, or you
remember or discover something you didn't mention in the initial
report, 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>
remember or discover something you did not mention in the
initial report, 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>
<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 PR can be closed, and, if possible,
explaining how or when the problem was fixed.</para>
above) saying that the problem report can be closed, and, if
possible, explaining how or when the problem was fixed.</para>
</sect1>
</article>