Date: Thu, 13 Mar 2014 04:15:32 +0000 (UTC) From: Warren Block <wblock@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r44226 - head/en_US.ISO8859-1/articles/problem-reports Message-ID: <201403130415.s2D4FWs1076335@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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@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@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 ***
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201403130415.s2D4FWs1076335>