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

Fix typos and markup nits.

Browse source 
Submitted by:	cmc, tmm
This commit is contained in:
Dag-Erling Smørgrav 2001-11-23 02:15:00 +00:00
parent 79ef787404
commit 71749510f6
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=11275
1 changed files with 55 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -38,9 +38,9 @@ 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". Similarily, one of the most
"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 aren't really problem reports but
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>
@ -74,10 +74,10 @@ FreeBSD Entities//EN"> %freebsd;
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 - 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 isn't? As a
<para>So how do you determine what's 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
@ -93,6 +93,7 @@ FreeBSD Entities//EN"> %freebsd;
good idea to air these on the mailing lists before
submitting a problem report.</para>
</listitem>
<listitem>
<para>Notification of updates to externally maintained
software (mainly ports, but also externally maintained base
@ -133,19 +134,23 @@ FreeBSD Entities//EN"> %freebsd;
<listitem>
<para>The FAQ.</para>
</listitem>
<listitem>
<para>The mailing lists - if you're not subscribed, use the
searchable archives on the FreeBSD web site. If your
<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
posting a message about it and waiting a few days to see if
someone can spot something you've overlooked.</para>
</listitem>
<listitem>
<para>Optionally, the entire web - 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 through.</para>
<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
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
@ -236,32 +241,39 @@ FreeBSD Entities//EN"> %freebsd;
The default value of <literal>current-users</literal> is
correct, even if you run FreeBSD-STABLE.</para>
</listitem>
<listitem>
<para><emphasis>Originator:</emphasis> This is normally
prefilled with the gecos field of the currently logged-in
user. Please specify your real name, optionally followed
by your email address in angle brackets.</para>
</listitem>
<listitem>
<para><emphasis>Organization:</emphasis> Whatever you feel
like. This field is not used for anything
significant.</para>
</listitem>
<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 - the
PR database is distributed worldwide by CVSup.</para>
there is no such thing as a confidential FreeBSD PR
&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>
<para>If your problem report includes a patch, please have
the synopsis start with <literal>[PATCH]</literal>.</para>
</listitem>
<listitem>
<para><emphasis>Severity:</emphasis> One of
<literal>non-critical</literal>,
@ -271,13 +283,15 @@ FreeBSD Entities//EN"> %freebsd;
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 theie problems.</para>
overrate their problems.</para>
</listitem>
<listitem>
<para><emphasis>Priority:</emphasis> One of
<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>
@ -286,74 +300,91 @@ FreeBSD Entities//EN"> %freebsd;
<para><literal>advocacy:</literal> problems relating to
FreeBSD's public image. Rarely used.</para>
</listitem>
<listitem>
<para><literal>alpha:</literal> problems specific to the
Alpha platform.</para>
</listitem>
<listitem>
<para><literal>bin:</literal> problems with userland
programs in the base system.</para>
</listitem>
<listitem>
<para><literal>conf:</literal> problems with
configuration files, default values etc.</para>
</listitem>
<listitem>
<para><literal>docs:</literal> problems with man pages
or on-line documentation.</para>
</listitem>
<listitem>
<para><literal>gnu:</literal> problems with GNU software
such as &man.gcc.1; or &man.grep.1;.</para>
</listitem>
<listitem>
<para><literal>i386:</literal> problems specific to the
i386 platform.</para>
</listitem>
<listitem>
<para><literal>kern:</literal> problems with
kernel.</para>
</listitem>
<listitem>
<para><literal>misc:</literal> anything that doesn't fit
in any of the other categories.</para>
</listitem>
<listitem>
<para><literal>ports:</literal> problems relating to the
ports tree.</para>
</listitem>
<listitem>
<para><literal>sparc:</literal> problems specific to the
Sparc platform.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para><emphasis>Class:</emphasis> Choose one of the
following:</para>
<itemizedlist>
<listitem>
<para><literal>sw-bug:</literal> software bugs..</para>
<para><literal>sw-bug:</literal> software bugs.</para>
</listitem>
<listitem>
<para><literal>doc-bug:</literal> errors in
documentation.</para>
</listitem>
<listitem>
<para><literal>change-request:</literal> requests for
additional features or changes in existing
features.</para>
</listitem>
<listitem>
<para><literal>update:</literal> updates to ports or
other contributed software.</para>
</listitem>
<listitem>
<para><literal>maintainer-update:</literal> updates to
ports for which you are the maintainer.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para><emphasis>Release:</emphasis> The version of FreeBSD
that you are running. This is filled out automatically by
@ -373,11 +404,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. -
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.
@ -386,10 +418,12 @@ 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
@ -404,9 +438,9 @@ FreeBSD Entities//EN"> %freebsd;
<sect2>
<title>Sending off the PR</title>
<para>Once you're done filling out the template 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
<para>Once you're 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>e</userinput> to restart the editor and make
further modifications, or <userinput>a</userinput> to abort.
@ -433,7 +467,7 @@ FreeBSD Entities//EN"> %freebsd;
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,
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