Whitespace cleanup + use <section> instead of <sect[12]>.
Translators can safely ignore this commit.
This commit is contained in:
Dag-Erling Smørgrav
parent
0839c1ab7a
commit
23cba8b041
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=15910
1 changed files with 149 additions and 149 deletions
|
|
@ -13,7 +13,7 @@
|
|||
|
||||
<abstract>
|
||||
<para>This article describes how to best formulate and submit a
|
||||
problem report to the FreeBSD Project.</para>
|
||||
problem report to the FreeBSD Project.</para>
|
||||
</abstract>
|
||||
|
||||
<authorgroup>
|
||||
|
|
@ -27,7 +27,7 @@
|
|||
|
||||
<indexterm><primary>problem reports</primary></indexterm>
|
||||
|
||||
<sect1 id="pr-intro">
|
||||
<section id="pr-intro">
|
||||
<title>Introduction</title>
|
||||
|
||||
<para>One of the most frustrating experiences one can have as a
|
||||
|
|
@ -54,9 +54,9 @@
|
|||
chronologically, so you should read through the entire document
|
||||
before submitting a problem report, rather than treat it as a
|
||||
step-by-step tutorial.</para>
|
||||
</sect1>
|
||||
</section>
|
||||
|
||||
<sect1 id="pr-when">
|
||||
<section id="pr-when">
|
||||
<title>When to submit a problem report</title>
|
||||
|
||||
<para>There are many types of problems, and not all of them should
|
||||
|
|
@ -87,16 +87,16 @@
|
|||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Requests for feature enhancements. It is generally a
|
||||
good idea to air these on the mailing lists before
|
||||
submitting a problem report.</para>
|
||||
<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>
|
||||
|
||||
<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>
|
||||
<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>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
|
|
@ -115,9 +115,9 @@
|
|||
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>
|
||||
</section>
|
||||
|
||||
<sect1 id="pr-prep">
|
||||
<section id="pr-prep">
|
||||
<title>Preparations</title>
|
||||
|
||||
<para>A good rule to follow is to always do a background search
|
||||
|
|
@ -130,34 +130,34 @@
|
|||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>The FAQ.</para>
|
||||
<para>The FAQ.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>The
|
||||
<ulink
|
||||
URL="../../books/handbook/eresources.html#ERESOURCES-MAIL">mailing
|
||||
lists</ulink>—if you are not subscribed, use
|
||||
<ulink
|
||||
URL="http://www.FreeBSD.org/search/search.html#mailinglists">the
|
||||
searchable archives</ulink> on the FreeBSD web site. If your
|
||||
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>
|
||||
<para>The
|
||||
<ulink
|
||||
URL="../../books/handbook/eresources.html#ERESOURCES-MAIL">mailing
|
||||
lists</ulink>—if you are not subscribed, use
|
||||
<ulink
|
||||
URL="http://www.FreeBSD.org/search/search.html#mailinglists">the
|
||||
searchable archives</ulink> on the FreeBSD web site. If your
|
||||
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>
|
||||
</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 did not know of or had not thought to search
|
||||
through.</para>
|
||||
<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 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 is a fair chance it has already
|
||||
been reported.</para>
|
||||
<para>Finally, the FreeBSD PR database. Unless your problem
|
||||
is recent or obscure, there is a fair chance it has already
|
||||
been reported.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
|
|
@ -180,9 +180,9 @@
|
|||
submit your problem report, there is a good chance that it will
|
||||
go unnoticed for a while, until someone re-categorizes
|
||||
it.</para>
|
||||
</sect1>
|
||||
</section>
|
||||
|
||||
<sect1 id="pr-writing">
|
||||
<section id="pr-writing">
|
||||
<title>Writing the problem report</title>
|
||||
|
||||
<para>Now that you have decided that your issue merits a problem
|
||||
|
|
@ -192,58 +192,58 @@
|
|||
environment variable is set to something sensible, and run
|
||||
&man.send-pr.1;.</para>
|
||||
|
||||
<sect2>
|
||||
<section>
|
||||
<title>Attaching patches or files</title>
|
||||
|
||||
<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
|
||||
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>
|
||||
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
|
||||
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>Do not worry about binary files, they will be automatically
|
||||
encoded so as not to upset your mail agent.</para>
|
||||
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
|
||||
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>
|
||||
<option>-c</option> or <option>-u</option> option to
|
||||
&man.diff.1; to create a context or unified diff, 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>You should also take note that unless you explicitly
|
||||
specify otherwise in your PR, any patches you submit will be
|
||||
assumed to be licensed under the same terms as the original
|
||||
file you modified.</para>
|
||||
</sect2>
|
||||
specify otherwise in your PR, any patches you submit will be
|
||||
assumed to be licensed under the same terms as the original
|
||||
file you modified.</para>
|
||||
</section>
|
||||
|
||||
<sect2>
|
||||
<section>
|
||||
<title>Filling out the template</title>
|
||||
|
||||
<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. Do not worry
|
||||
about the comments; they will be removed automatically if you
|
||||
do not modify them or remove them yourself.</para>
|
||||
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>
|
||||
|
||||
<para>At the top of the template, below the
|
||||
<literal>SEND-PR:</literal> lines, are the email headers. You
|
||||
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
|
||||
adding one or more email addresses to the
|
||||
<literal>Cc:</literal> header.</para>
|
||||
<literal>SEND-PR:</literal> lines, are the email headers. You
|
||||
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
|
||||
adding one or more email addresses to the
|
||||
<literal>Cc:</literal> header.</para>
|
||||
|
||||
<para>Next comes a series of single-line fields:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<listitem>
|
||||
<para><emphasis>Submitter-Id:</emphasis> Do not change this.
|
||||
The default value of <literal>current-users</literal> is
|
||||
correct, even if you run FreeBSD-STABLE.</para>
|
||||
|
|
@ -251,9 +251,9 @@
|
|||
|
||||
<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>
|
||||
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>
|
||||
|
|
@ -264,40 +264,40 @@
|
|||
|
||||
<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 problem
|
||||
report—the PR database is distributed worldwide by
|
||||
<application>CVSup</application>.</para>
|
||||
to <literal>no</literal>, changing it makes no sense as
|
||||
there is no such thing as a confidential FreeBSD problem
|
||||
report—the PR database is distributed worldwide by
|
||||
<application>CVSup</application>.</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 problem report
|
||||
email, and is used in problem report listings and
|
||||
summaries; problem reports with obscure synopses tend to
|
||||
get ignored.</para>
|
||||
short and accurate description of the problem. The
|
||||
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>
|
||||
the synopsis start with <literal>[PATCH]</literal>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><emphasis>Severity:</emphasis> One of
|
||||
<literal>non-critical</literal>,
|
||||
<literal>serious</literal> or
|
||||
<literal>critical</literal>. Do not overreact; refrain
|
||||
from labeling your problem <literal>critical</literal>
|
||||
unless it really is (e.g. <username>root</username> exploit, easily
|
||||
reproducible panic). Developers tend to ignore this and
|
||||
the next field, precisely because problem report
|
||||
submitters tend to overrate their problems.</para>
|
||||
<literal>non-critical</literal>,
|
||||
<literal>serious</literal> or
|
||||
<literal>critical</literal>. Do not overreact; refrain
|
||||
from labeling your problem <literal>critical</literal>
|
||||
unless it really is (e.g. <username>root</username> exploit, easily
|
||||
reproducible panic). Developers tend to ignore this and
|
||||
the next field, precisely because problem report
|
||||
submitters tend to 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>
|
||||
<literal>low</literal>, <literal>medium</literal> or
|
||||
<literal>high</literal>. See above.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
|
|
@ -306,37 +306,37 @@
|
|||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>advocacy:</literal> problems relating to
|
||||
FreeBSD's public image. Rarely used.</para>
|
||||
FreeBSD's public image. Rarely used.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>alpha:</literal> problems specific to the
|
||||
Alpha platform.</para>
|
||||
Alpha platform.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>bin:</literal> problems with userland
|
||||
programs in the base system.</para>
|
||||
programs in the base system.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>conf:</literal> problems with
|
||||
configuration files, default values etc.</para>
|
||||
configuration files, default values etc.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>docs:</literal> problems with manual pages
|
||||
or on-line documentation.</para>
|
||||
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>
|
||||
such as &man.gcc.1; or &man.grep.1;.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>i386:</literal> problems specific to the
|
||||
i386 platform.</para>
|
||||
i386 platform.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
|
|
@ -351,27 +351,27 @@
|
|||
|
||||
<listitem>
|
||||
<para><literal>kern:</literal> problems with
|
||||
kernel.</para>
|
||||
kernel.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>misc:</literal> anything that does not fit
|
||||
in any of the other categories.</para>
|
||||
in any of the other categories.</para>
|
||||
</listitem>
|
||||
|
||||
|
||||
<listitem>
|
||||
<para><literal>ports:</literal> problems relating to the
|
||||
ports tree.</para>
|
||||
ports tree.</para>
|
||||
</listitem>
|
||||
|
||||
|
||||
<listitem>
|
||||
<para><literal>powerpc:</literal> problems specific to the
|
||||
PowerPC platform.</para>
|
||||
PowerPC platform.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para><literal>sparc64:</literal> problems specific to the
|
||||
SPARC platform.</para>
|
||||
SPARC platform.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
|
|
@ -385,35 +385,35 @@
|
|||
</listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
|
||||
|
||||
<listitem>
|
||||
<para><emphasis>Class:</emphasis> Choose one of the
|
||||
following:</para>
|
||||
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><literal>sw-bug:</literal> software bugs.</para>
|
||||
</listitem>
|
||||
|
||||
|
||||
<listitem>
|
||||
<para><literal>doc-bug:</literal> errors in
|
||||
documentation.</para>
|
||||
documentation.</para>
|
||||
</listitem>
|
||||
|
||||
|
||||
<listitem>
|
||||
<para><literal>change-request:</literal> requests for
|
||||
additional features or changes in existing
|
||||
features.</para>
|
||||
additional features or changes in existing
|
||||
features.</para>
|
||||
</listitem>
|
||||
|
||||
|
||||
<listitem>
|
||||
<para><literal>update:</literal> updates to ports or
|
||||
other contributed software.</para>
|
||||
other contributed software.</para>
|
||||
</listitem>
|
||||
|
||||
|
||||
<listitem>
|
||||
<para><literal>maintainer-update:</literal> updates to
|
||||
ports for which you are the maintainer.</para>
|
||||
ports for which you are the maintainer.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</listitem>
|
||||
|
|
@ -430,17 +430,17 @@
|
|||
<para>Finally, there is a series of multi-line fields:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<listitem>
|
||||
<para><emphasis>Environment:</emphasis> This should
|
||||
describe, as accurately as possible, the environment in
|
||||
which the problem has been observed. This includes the
|
||||
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
|
||||
occurs.</para>
|
||||
describe, as accurately as possible, the environment in
|
||||
which the problem has been observed. This includes the
|
||||
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
|
||||
occurs.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
|
|
@ -466,33 +466,33 @@
|
|||
leave this field blank than to speculate.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</sect2>
|
||||
</section>
|
||||
|
||||
<sect2>
|
||||
<section>
|
||||
<title>Sending off the problem report</title>
|
||||
|
||||
<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 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
|
||||
disk (&man.send-pr.1; will tell you the filename before it
|
||||
terminates), so you can edit it at your leisure, or maybe
|
||||
transfer it to a system with better net connectivity, before
|
||||
sending it with the <option>-f</option> to
|
||||
&man.send-pr.1;:</para>
|
||||
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 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
|
||||
disk (&man.send-pr.1; will tell you the filename before it
|
||||
terminates), so you can edit it at your leisure, or maybe
|
||||
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>
|
||||
|
||||
<para>This will read the specified file, validate the contents,
|
||||
strip comments and send it off.</para>
|
||||
</sect2>
|
||||
strip comments and send it off.</para>
|
||||
</section>
|
||||
|
||||
</sect1>
|
||||
</section>
|
||||
|
||||
<sect1 id="pr-followup">
|
||||
<section id="pr-followup">
|
||||
<title>Follow-up</title>
|
||||
|
||||
<para>Once your problem report has been filed, you will receive a
|
||||
|
|
@ -516,9 +516,9 @@
|
|||
gone away, just send a follow-up (in the manner prescribed
|
||||
above) saying that the problem report can be closed, and, if
|
||||
possible, explaining how or when the problem was fixed.</para>
|
||||
</sect1>
|
||||
</section>
|
||||
|
||||
<sect1 id="pr-further">
|
||||
<section id="pr-further">
|
||||
<title>Further Reading</title>
|
||||
|
||||
<para>This is a list of resources relevant to the proper writing
|
||||
|
|
@ -526,19 +526,19 @@
|
|||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para><ulink
|
||||
<para><ulink
|
||||
url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html">
|
||||
How to Report Bugs Effectively</ulink>—an excellent
|
||||
essay by Simon G. Tatham on composing useful (non-FreeBSD-specific)
|
||||
problem reports.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para><ulink
|
||||
url="../../articles/pr-guidelines/article.html">Problem
|
||||
Report Handling Guidelines</ulink>—valuable insight
|
||||
into how problem reports are handled by the FreeBSD
|
||||
developers.</para>
|
||||
<para><ulink
|
||||
url="../../articles/pr-guidelines/article.html">Problem
|
||||
Report Handling Guidelines</ulink>—valuable insight
|
||||
into how problem reports are handled by the FreeBSD
|
||||
developers.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
</section>
|
||||
</article>
|
||||
|
|
|
|||
Loading…
Reference in a new issue