svn commit: r44226 - head/en_US.ISO8859-1/articles/problem-reports
Warren Block
wblock at FreeBSD.org
Thu Mar 13 04:15:32 UTC 2014
Author: wblock
Date: Thu Mar 13 04:15:32 2014
New Revision: 44226
URL: http://svnweb.freebsd.org/changeset/doc/44226
Log:
Whitespace-only fixes, translators please ignore.
Modified:
head/en_US.ISO8859-1/articles/problem-reports/article.xml
Modified: head/en_US.ISO8859-1/articles/problem-reports/article.xml
==============================================================================
--- head/en_US.ISO8859-1/articles/problem-reports/article.xml Thu Mar 13 03:28:47 2014 (r44225)
+++ head/en_US.ISO8859-1/articles/problem-reports/article.xml Thu Mar 13 04:15:32 2014 (r44226)
@@ -1,9 +1,12 @@
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
-<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
- <info><title>Writing &os; Problem Reports</title>
-
+<article xmlns="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
+ xml:lang="en">
+
+ <info>
+ <title>Writing &os; Problem Reports</title>
<legalnotice xml:id="trademarks" role="trademarks">
&tm-attrib.freebsd;
@@ -24,9 +27,20 @@
</abstract>
<authorgroup>
- <author><personname><firstname>Dag-Erling</firstname><surname>Smørgrav</surname></personname><contrib>Contributed by </contrib></author>
-
- <author><personname><firstname>Mark</firstname><surname>Linimon</surname></personname></author>
+ <author>
+ <personname>
+ <firstname>Dag-Erling</firstname>
+ <surname>Smørgrav</surname>
+ </personname>
+ <contrib>Contributed by </contrib>
+ </author>
+
+ <author>
+ <personname>
+ <firstname>Mark</firstname>
+ <surname>Linimon</surname>
+ </personname>
+ </author>
</authorgroup>
</info>
@@ -66,23 +80,21 @@
<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 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
+ 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 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 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
+ <emphasis>not</emphasis> the right 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 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. When looking
@@ -99,63 +111,66 @@
system components such as BIND or various GNU
utilities).</para>
- <para>For unmaintained ports (<varname>MAINTAINER</varname> contains
- <literal>ports at FreeBSD.org</literal>), such update notifications
- might get picked up by an interested
- committer, or you might be asked to provide a patch to update
- the port; providing it upfront will greatly improve your chances
- that the port will get updated in a timely manner.</para>
-
- <para>If the port is maintained, PRs announcing new upstream releases
- are usually not very useful since they generate supplementary work
- for the committers, and the maintainer likely knows already there is
- a new version, they have probably worked with the developers on it,
- they are probably testing to see there is no regression, etc.</para>
-
- <para>In either case, following the process described in <link xlink:href="&url.books.porters-handbook;/port-upgrading.html">Porter's
- Handbook</link> will yield the best results. (You might
- also wish to read <link xlink:href="&url.articles.contributing-ports;/article.html">
- Contributing to the FreeBSD Ports Collection</link>.)
- </para>
+ <para>For unmaintained ports (<varname>MAINTAINER</varname>
+ contains <literal>ports at FreeBSD.org</literal>), such update
+ notifications might get picked up by an interested
+ committer, or you might be asked to provide a patch to
+ update the port; providing it upfront will greatly improve
+ your chances that the port will get updated in a timely
+ manner.</para>
+
+ <para>If the port is maintained, PRs announcing new upstream
+ releases are usually not very useful since they generate
+ supplementary work for the committers, and the maintainer
+ likely knows already there is a new version, they have
+ probably worked with the developers on it, they are probably
+ testing to see there is no regression, etc.</para>
+
+ <para>In either case, following the process described in <link
+ xlink:href="&url.books.porters-handbook;/port-upgrading.html">Porter's
+ Handbook</link> will yield the best results. (You might
+ also wish to read <link
+ xlink:href="&url.articles.contributing-ports;/article.html">Contributing
+ to the FreeBSD Ports Collection</link>.)</para>
</listitem>
</itemizedlist>
- <para>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 is 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. To make matters worse, often
- these kinds of bugs are actually caused by failing hard drives
- or overheating processors — you should always try to rule
- out these causes, whenever possible, before submitting a PR.</para>
-
- <para>Next, to decide to whom you should file your problem
- report, you need to understand that the software that makes
- up &os; is composed of several different elements:</para>
+ <para>A bug that cannot 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 is
+ 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. To make matters worse, often these kinds of
+ bugs are actually caused by failing hard drives or overheating
+ processors — you should always try to rule out these
+ causes, whenever possible, before submitting a PR.</para>
+
+ <para>Next, to decide to whom you should file your problem report,
+ you need to understand that the software that makes up &os; is
+ composed of several different elements:</para>
<itemizedlist>
<listitem>
<para>Code in the base system that is written and maintained
- by &os; contributors, such as the kernel, the C library,
- and the device drivers (categorized as <literal>kern</literal>);
+ by &os; contributors, such as the kernel, the C library, and
+ the device drivers (categorized as <literal>kern</literal>);
the binary utilities (<literal>bin</literal>); the manual
- pages and documentation (<literal>docs</literal>); and
- the web pages (<literal>www</literal>). All bugs in
- these areas should be reported to the &os; developers.</para>
+ pages and documentation (<literal>docs</literal>); and the
+ web pages (<literal>www</literal>). All bugs in these areas
+ should be reported to the &os; developers.</para>
</listitem>
<listitem>
<para>Code in the base system that is written and maintained
by others, and imported into &os; and adapted. Examples
include <application>bind</application>, &man.gcc.1;, and
- &man.sendmail.8;. Most bugs in these areas should be reported
- to the &os; developers; but in some cases they may need to be
- reported to the original authors instead if the problems are
- not &os;-specific. Usually these bugs will fall under either
- the <literal>bin</literal> or <literal>gnu</literal>
- categories.</para>
+ &man.sendmail.8;. Most bugs in these areas should be
+ reported to the &os; developers; but in some cases they may
+ need to be reported to the original authors instead if the
+ problems are not &os;-specific. Usually these bugs will
+ fall under either the <literal>bin</literal> or
+ <literal>gnu</literal> categories.</para>
</listitem>
<listitem>
@@ -163,38 +178,37 @@
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,
- 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>
+ 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, 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, 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
- the topic. It is not possible for &os; to fix problems in
- anything other than certain recent branches of the base system,
- so filing a bug report about an older version will probably
- only result in a developer advising you to upgrade to a
- supported version to see if the problem still recurs. The
- Security Officer team maintains the
+ <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, 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 the
+ topic. It is not possible for &os; to fix problems in anything
+ other than certain recent branches of the base system, so filing
+ a bug report about an older version will probably only result in
+ a developer advising you to upgrade to a supported version to
+ see if the problem still recurs. The Security Officer team
+ maintains the
<link xlink:href="&url.base;/security/">list of supported
- versions</link>.</para>
+ versions</link>.</para>
<para>If the problem is in a port, note that you must first
- upgrade to the latest version of the Ports Collection and see
- if the problem still applies. Due to the rapid pace of changes
- in these applications, it is infeasible for &os; to support
+ upgrade to the latest version of the Ports Collection and see if
+ the problem still applies. Due to the rapid pace of changes in
+ these applications, it is infeasible for &os; to support
anything other than the absolute latest versions, and problems
- with older version of applications simply cannot be fixed.</para>
+ with older version of applications simply cannot be
+ fixed.</para>
</section>
<section xml:id="pr-prep">
@@ -210,24 +224,24 @@
<itemizedlist>
<listitem>
- <para>The &os;
- <link xlink:href="&url.books.faq;/index.html">Frequently Asked
+ <para>The &os; <link
+ xlink:href="&url.books.faq;/index.html">Frequently Asked
Questions</link> (FAQ) list.
- The FAQ attempts to provide answers for a wide range of questions,
- such as those concerning
+ The FAQ attempts to provide answers for a wide range of
+ questions, such as those concerning
<link xlink:href="&url.books.faq;/hardware.html">hardware
compatibility</link>,
<link xlink:href="&url.books.faq;/applications.html">user
- applications</link>,
- and <link xlink:href="&url.books.faq;/kernelconfig.html">kernel
+ applications</link>, and
+ <link xlink:href="&url.books.faq;/kernelconfig.html">kernel
configuration</link>.</para>
</listitem>
<listitem>
- <para>The
- <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
+ <para>The <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 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
@@ -243,35 +257,34 @@
</listitem>
<listitem>
- <para>Next, the searchable
- <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">
- &os; PR database</link> (GNATS). Unless the problem
- is recent or obscure, there is a fair chance it has already
- been reported.</para>
+ <para>Next, the searchable <link
+ xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">&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, attempt to see if existing
- documentation in the source base addresses your problem.</para>
+ documentation in the source base addresses your
+ problem.</para>
- <para>For the base &os; code, you should
- 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
- another—especially if you are upgrading to the
- &os.current; branch).</para>
-
- <para>However, if the problem is in something that was installed
- as a part of the &os; Ports Collection, you should refer to
- <filename>/usr/ports/UPDATING</filename> (for individual ports)
- or <filename>/usr/ports/CHANGES</filename> (for changes
- that affect the entire Ports Collection).
- <uri xlink:href="http://svnweb.freebsd.org/ports/head/UPDATING?view=log">http://svnweb.freebsd.org/ports/head/UPDATING?view=log</uri>
- and
- <uri xlink:href="http://svnweb.freebsd.org/ports/head/CHANGES?view=log">http://svnweb.freebsd.org/ports/head/CHANGES?view=log</uri>
+ <para>For the base &os; code, you should 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 another—especially if you are upgrading to
+ the &os.current; branch).</para>
+
+ <para>However, if the problem is in something that was
+ installed as a part of the &os; Ports Collection, you should
+ refer to <filename>/usr/ports/UPDATING</filename> (for
+ individual ports) or <filename>/usr/ports/CHANGES</filename>
+ (for changes that affect the entire Ports Collection). <uri
+ xlink:href="http://svnweb.freebsd.org/ports/head/UPDATING?view=log">http://svnweb.freebsd.org/ports/head/UPDATING?view=log</uri>
+ and <uri
+ xlink:href="http://svnweb.freebsd.org/ports/head/CHANGES?view=log">http://svnweb.freebsd.org/ports/head/CHANGES?view=log</uri>
are also available via svnweb.</para>
</listitem>
</itemizedlist>
@@ -281,10 +294,10 @@
<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
- the actual problem report. Before we get into the mechanics
- of the program used to generate and submit PRs, here are some
- tips and tricks to help make sure that your PR will be most
+ report, and that it is a &os; problem, it is time to write the
+ actual problem report. Before we get into the mechanics of the
+ program used to generate and submit PRs, here are some tips and
+ tricks to help make sure that your PR will be most
effective.</para>
<section xml:id="pr-writing-tips">
@@ -293,10 +306,10 @@
<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
+ 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
@@ -307,114 +320,127 @@
<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 ports-mgmt/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>
+ 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 ports-mgmt/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> (including the brackets) 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>
+ looked at than one without. If you are including one, put
+ the string <literal>[patch]</literal> (including the
+ brackets) 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> (including the brackets) at the beginning of
- your synopsis line, and you definitely should 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.</para>
+ <literal>[maintainer update]</literal> (including the
+ brackets) at the beginning of your synopsis line, and you
+ definitely should 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.</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.</para>
+ <para><emphasis>Be specific.</emphasis> The more information
+ you supply about what problem you are having, the better
+ your chance of getting a response.</para>
<itemizedlist>
<listitem>
<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 <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
- will ask, because fixes (especially for high-profile
- problems) tend to get committed very quickly, and
- &os.current; users are expected to keep up.</para>
+ 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
+ <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 will ask, because fixes (especially for
+ high-profile problems) tend to get committed very
+ quickly, and &os.current; users are expected to keep
+ up.</para>
</listitem>
<listitem>
<para>Include which global options you have specified in
your <filename>make.conf</filename>. Note: specifying
<literal>-O2</literal> and above to &man.gcc.1; is
- known to be buggy in many situations. While the
- &os; developers will accept patches, they are
- generally unwilling to investigate such issues due
- to simple lack of time and volunteers, and may
- instead respond that this just is not supported.</para>
+ known to be buggy in many situations. While the &os;
+ developers will accept patches, they are generally
+ unwilling to investigate such issues due to simple
+ lack of time and volunteers, and may instead respond
+ that this just is not supported.</para>
</listitem>
<listitem>
<para>If the problem can be reproduced easily, include
information that will help a developer to reproduce it
themselves. If a problem can be demonstrated with
- specific input then include an example of that input if
- possible, and include both the actual and the expected
- output. If this data is large or cannot be made public,
- then do try to create a minimal file that exhibits the
- same issue and that can be included within the PR.</para>
+ specific input then include an example of that input
+ if possible, and include both the actual and the
+ expected output. If this data is large or cannot be
+ made public, then do try to create a minimal file that
+ exhibits the same issue and that can be included
+ within the PR.</para>
</listitem>
<listitem>
<para>If this is a kernel problem, then be prepared to
- supply the following information. (You do not
- have to include these by default, which only tends to
- fill up the database, but you should include excerpts
- that you think might be relevant):</para>
+ supply the following information. (You do not have to
+ include these by default, which only tends to fill up
+ the database, but you should include excerpts that you
+ think might be relevant):</para>
<itemizedlist>
<listitem>
<para>your kernel configuration (including which
hardware devices you have installed)</para>
</listitem>
+
<listitem>
- <para>whether or not you have debugging options enabled
- (such as <literal>WITNESS</literal>), and if so,
- whether the problem persists when you change the
- sense of that option</para>
+ <para>whether or not you have debugging options
+ enabled (such as <literal>WITNESS</literal>), and
+ if so, whether the problem persists when you
+ change the sense of that option</para>
</listitem>
+
<listitem>
- <para>the full text of any backtrace, panic or other console
- output, or entries in <filename>/var/log/messages</filename>,
- if any were generated</para>
+ <para>the full text of any backtrace, panic or other
+ console output, or entries in
+ <filename>/var/log/messages</filename>, if any
+ were generated</para>
</listitem>
+
<listitem>
- <para>the output of <command>pciconf -l</command> and
- relevant parts of your <command>dmesg</command> output if
- your problem relates to a specific piece of hardware</para>
+ <para>the output of <command>pciconf -l</command>
+ and relevant parts of your
+ <command>dmesg</command> output if your problem
+ relates to a specific piece of hardware</para>
</listitem>
+
<listitem>
<para>the fact that you have read
- <filename>src/UPDATING</filename> and that your problem
- is not listed there (someone is guaranteed to ask)</para>
+ <filename>src/UPDATING</filename> and that your
+ problem is not listed there (someone is guaranteed
+ to ask)</para>
</listitem>
+
<listitem>
<para>whether or not you can run any other kernel as
a fallback (this is to rule out hardware-related
@@ -435,52 +461,56 @@
<listitem>
<para>which ports you have installed</para>
</listitem>
+
<listitem>
<para>any environment variables that override the
defaults in <filename>bsd.port.mk</filename>, such
as <varname>PORTSDIR</varname></para>
</listitem>
+
<listitem>
<para>the fact that you have read
- <filename>ports/UPDATING</filename> and that your problem
- is not listed there (someone is guaranteed to ask)</para>
+ <filename>ports/UPDATING</filename> and that your
+ problem is not listed there (someone is guaranteed
+ to ask)</para>
</listitem>
</itemizedlist>
</listitem>
-
</itemizedlist>
-
</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
+ <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>
+ 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
+ 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
- <uri xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query</uri>.
+ minute or two to use the web-based search engine at <uri
+ xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query</uri>.
(Of course, everyone is guilty of forgetting to do this
now and then.)</para>
</listitem>
<listitem>
<para><emphasis>Report only one issue per Problem
- Report.</emphasis> Avoid including two or more problems
+ Report.</emphasis> Avoid including two or more problems
within the same report unless they are related. When
submitting patches, avoid adding multiple features or
- fixing multiple bugs in the same PR unless they are closely
- related—such PRs often take longer to resolve.</para>
+ fixing multiple bugs in the same PR unless they are
+ closely related—such PRs often take longer to
+ resolve.</para>
</listitem>
<listitem>
@@ -490,18 +520,18 @@
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 <uri xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">http://www.FreeBSD.org/search/search.html#mailinglists</uri>
+ at <uri
+ xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">http://www.FreeBSD.org/search/search.html#mailinglists</uri>
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>
+ <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>
@@ -514,34 +544,35 @@
<envar>VISUAL</envar> is not set) environment variable is set
to something sensible.</para>
- <para>Make sure that mail delivery is working.
- &man.send-pr.1; uses mail messages for the submission and
- 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 mail delivery is working. &man.send-pr.1;
+ uses mail messages for the submission and 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 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 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>
+ 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 to use of the
<link xlink:href="&url.base;/send-pr.html"> web-based
- 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 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>
+ 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 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 xml:id="pr-writing-attaching-patches">
@@ -556,48 +587,49 @@
<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>
+ <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>
+ <para>Do not worry about binary files, they will be
+ automatically encoded so as not to upset your mail
+ agent.</para>
<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
- you modified so the developers who read your report will be
- able to apply them easily. For problems with the kernel or the
- base utilities, a patch against &os.current; (the HEAD
- Subversion branch) is preferred since all new code should be applied
- and tested there first. After appropriate or substantial testing
- has been done, the code will be merged/migrated to the &os.stable;
- branch.</para>
+ <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 you modified so the developers who read your report will
+ be able to apply them easily. For problems with the kernel or
+ the base utilities, a patch against &os.current; (the HEAD
+ Subversion branch) is preferred since all new code should be
+ applied and tested there first. After appropriate or
+ substantial testing has been done, the code will be
+ merged/migrated to the &os.stable; branch.</para>
<para>If you attach a patch inline, instead of as an attachment,
- note that the most common problem by far is the tendency of some
- email programs to render tabs as spaces, which will completely
- ruin anything intended to be part of a Makefile.</para>
+ note that the most common problem by far is the tendency of
+ some email programs to render tabs as spaces, which will
+ completely ruin anything intended to be part of a
+ Makefile.</para>
<para>Do not send patches as attachments using
- <command>Content-Transfer-Encoding: quoted-printable</command>.
- These will perform character escaping and the entire patch
- will be useless.</para>
+ <command>Content-Transfer-Encoding:
+ quoted-printable</command>. These will perform character
+ escaping and the entire patch will be useless.</para>
<para>Also note that while including small patches in a PR is
- generally all right—particularly when they fix the problem
- described in the PR—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
- 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
- patch in a followup to the original PR. Finally, large
- patches simply increase the size of the database, since
- closed PRs are not actually deleted but instead kept and
- simply marked as <literal>closed</literal>.</para>
+ generally all right—particularly when they fix the
+ problem described in the PR—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 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 patch in a followup to the original PR. Finally, large
+ patches simply increase the size of the database, since closed
+ PRs are not actually deleted but instead kept and simply
+ marked as <literal>closed</literal>.</para>
<para>You should also take note that unless you explicitly
specify otherwise in your PR or in the patch itself, any
@@ -610,12 +642,12 @@
<para>The next section applies to the email method only:</para>
- <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
- do not modify them or remove them yourself.</para>
+ <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 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
@@ -649,26 +681,25 @@
<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., data corruption issues, serious
- regression from previous functionality in -CURRENT)
- or <literal>serious</literal> unless
- it is something that will affect many users (kernel
- panics or freezes; problems with
- particular device drivers or system utilities). &os;
- developers will not necessarily work on your problem faster
- if you inflate its importance since there are so many other
- people who have done exactly that — in fact, some
- developers pay little attention to this field
- because of this.</para>
+ <literal>serious</literal> or <literal>critical</literal>.
+ Do not overreact; refrain from labeling your problem
+ <literal>critical</literal> unless it really is (e.g.,
+ data corruption issues, serious regression from previous
+ functionality in -CURRENT) or <literal>serious</literal>
+ unless it is something that will affect many users (kernel
+ panics or freezes; problems with particular device drivers
+ or system utilities). &os; developers will not
+ necessarily work on your problem faster if you inflate its
+ importance since there are so many other people who have
+ done exactly that — in fact, some developers pay
+ little attention to this field because of this.</para>
<note>
<para>Security problems should <emphasis>not</emphasis>
- be filed in GNATS, because all GNATS information is public
- knowledge. Please send such problems according to our
- <link xlink:href="http://security.freebsd.org/#how">security
+ be filed in GNATS, because all GNATS information is
+ public knowledge. Please send such problems according
+ to our <link
+ xlink:href="http://security.freebsd.org/#how">security
report guidelines</link>.</para>
</note>
</listitem>
@@ -691,28 +722,27 @@
</itemizedlist>
<para>The next section describes fields that are common to both
- the email interface and the <link xlink:href="&url.base;/send-pr.html">web interface</link>:</para>
+ the email interface and the
+ <link xlink:href="&url.base;/send-pr.html">web
+ interface</link>:</para>
<itemizedlist>
-
<listitem>
- <para><emphasis>Originator:</emphasis>
- Please specify your real name, optionally followed
- by your email address in angle brackets.
- In the email interface, this is normally
+ <para><emphasis>Originator:</emphasis> Please specify your
+ real name, optionally followed by your email address in
+ angle brackets. In the email interface, this is normally
prefilled with the <literal>gecos</literal> field of the
- currently logged-in
- user.</para>
+ currently logged-in user.</para>
<note>
- <para>The email address you use will become public information
- and may become available to spammers. You should either
- have spam handling procedures in place, or use a temporary
- email account. However, please note that if you do not
- use a valid email account at all, we will not be able to
- ask you questions about your PR.</para>
+ <para>The email address you use will become public
+ information and may become available to spammers. You
+ should either have spam handling procedures in place, or
+ use a temporary email account. However, please note
+ that if you do not use a valid email account at all, we
+ will not be able to ask you questions about your
+ PR.</para>
</note>
-
</listitem>
<listitem>
@@ -729,90 +759,98 @@
summaries; problem reports with obscure synopses tend to
get ignored.</para>
- <para>As noted above, if your problem report includes a patch,
- please have the synopsis start with <literal>[patch]</literal> (including the brackets);
- if this is a ports PR and you are the
- maintainer, you may consider adding
- <literal>[maintainer update]</literal> (including the brackets) and set the
- <quote>Class</quote> of your PR to
- <literal>maintainer-update</literal>.</para>
+ <para>As noted above, if your problem report includes a
+ patch, please have the synopsis start with
+ <literal>[patch]</literal> (including the brackets); if
+ this is a ports PR and you are the maintainer, you may
+ consider adding <literal>[maintainer update]</literal>
+ (including the brackets) and set the <quote>Class</quote>
+ of your PR to <literal>maintainer-update</literal>.</para>
</listitem>
<listitem>
<para><emphasis>Category:</emphasis> Choose an appropriate
category.</para>
- <para>The first thing you need to do is to decide what part of
- the system your problem lies in. Remember, &os; is a
- complete operating system, which installs both a kernel, the
- standard libraries, many peripheral drivers, and a large number
- of utilities (the <quote>base system</quote>).
- However, there are thousands of additional applications in the
- Ports Collection. You'll first need to decide if the problem
- is in the base system or something installed via the Ports
+ <para>The first thing you need to do is to decide what part
+ of the system your problem lies in. Remember, &os; is a
+ complete operating system, which installs both a kernel,
+ the standard libraries, many peripheral drivers, and a
+ large number of utilities (the
+ <quote>base system</quote>). However, there are thousands
+ of additional applications in the Ports Collection.
+ You'll first need to decide if the problem is in the base
+ system or something installed via the Ports
Collection.</para>
<para>Here is a description of the major categories:</para>
<itemizedlist>
<listitem>
- <para>If a problem is with the kernel, the libraries (such
- as standard C library <literal>libc</literal>), or a
- peripheral driver in the base system, in general you will
- use the <literal>kern</literal> category. (There are a few
- exceptions; see below). In general these are things that are
- described in section 2, 3, or 4 of the manual pages.</para>
+ <para>If a problem is with the kernel, the libraries
+ (such as standard C library <literal>libc</literal>),
+ or a peripheral driver in the base system, in general
+ you will use the <literal>kern</literal> category.
+ (There are a few exceptions; see below). In general
+ these are things that are described in section 2, 3,
+ or 4 of the manual pages.</para>
</listitem>
<listitem>
<para>If a problem is with a binary program such as
- &man.sh.1; or &man.mount.8;, you will first need to determine
- whether these programs are in the base system or were added
- via the Ports Collection. If you are unsure, you can do
- <command>whereis <replaceable>programname</replaceable></command>.
- &os;'s convention for the Ports Collection is to install
- everything underneath
+ &man.sh.1; or &man.mount.8;, you will first need to
+ determine whether these programs are in the base
+ system or were added via the Ports Collection. If you
+ are unsure, you can do <command>whereis
+ <replaceable>programname</replaceable></command>.
+ &os;'s convention for the Ports Collection is to
+ install everything underneath
<filename class="directory">/usr/local</filename>,
- although this can be overridden by a system administrator.
- For these, you will use the <literal>ports</literal>
- category (yes, even if the port's category is
- <literal>www</literal>; see below). If the location is
+ although this can be overridden by a system
+ administrator. For these, you will use the
+ <literal>ports</literal> category (yes, even if the
+ port's category is <literal>www</literal>; see below).
+ If the location is
<filename class="directory">/bin</filename>,
<filename class="directory">/usr/bin</filename>,
<filename class="directory">/sbin</filename>, or
- <filename class="directory">/usr/sbin</filename>,
- it is part of the base system, and you should use the
- <literal>bin</literal> category. (A few programs, such as
- &man.gcc.1;, actually use the <literal>gnu</literal> category,
*** DIFF OUTPUT TRUNCATED AT 1000 LINES ***
More information about the svn-doc-all
mailing list