From owner-svn-doc-all@FreeBSD.ORG Thu Mar 13 04:15:32 2014 Return-Path: Delivered-To: svn-doc-all@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1 with cipher ADH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id AD9ACE6D; Thu, 13 Mar 2014 04:15:32 +0000 (UTC) Received: from svn.freebsd.org (svn.freebsd.org [IPv6:2001:1900:2254:2068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.freebsd.org (Postfix) with ESMTPS id 98C43E54; Thu, 13 Mar 2014 04:15:32 +0000 (UTC) Received: from svn.freebsd.org ([127.0.1.70]) by svn.freebsd.org (8.14.8/8.14.8) with ESMTP id s2D4FWBB076336; Thu, 13 Mar 2014 04:15:32 GMT (envelope-from wblock@svn.freebsd.org) Received: (from wblock@localhost) by svn.freebsd.org (8.14.8/8.14.8/Submit) id s2D4FWs1076335; Thu, 13 Mar 2014 04:15:32 GMT (envelope-from wblock@svn.freebsd.org) Message-Id: <201403130415.s2D4FWs1076335@svn.freebsd.org> From: Warren Block Date: Thu, 13 Mar 2014 04:15:32 +0000 (UTC) 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 X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.17 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 13 Mar 2014 04:15:32 -0000 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 @@ -
- Writing &os; Problem Reports - +
+ + + Writing &os; Problem Reports &tm-attrib.freebsd; @@ -24,9 +27,20 @@ - Dag-ErlingSmørgravContributed by - - MarkLinimon + + + Dag-Erling + Smørgrav + + Contributed by + + + + + Mark + Linimon + + @@ -66,23 +80,21 @@ 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 - not 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. - - So how does one determine what is a bug and what is not? As a - simple rule of thumb, the problem is not a - bug if it can be expressed as a question (usually of the form + not 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. + + So how does one determine what is a bug and what is not? As + a simple rule of thumb, the problem is not + a bug if it can be expressed as a question (usually of the form How do I do X? or Where can I find Y?). It 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). - For unmaintained ports (MAINTAINER contains - ports@FreeBSD.org), 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. - - 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. - - In either case, following the process described in Porter's - Handbook will yield the best results. (You might - also wish to read - Contributing to the FreeBSD Ports Collection.) - + For unmaintained ports (MAINTAINER + contains ports@FreeBSD.org), 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. + + 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. + + In either case, following the process described in Porter's + Handbook will yield the best results. (You might + also wish to read Contributing + to the FreeBSD Ports Collection.) - 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. - - 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: + 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. + + 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: 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 kern); + by &os; contributors, such as the kernel, the C library, and + the device drivers (categorized as kern); the binary utilities (bin); the manual - pages and documentation (docs); and - the web pages (www). All bugs in - these areas should be reported to the &os; developers. + pages and documentation (docs); and the + web pages (www). All bugs in these areas + should be reported to the &os; developers. Code in the base system that is written and maintained by others, and imported into &os; and adapted. Examples include bind, &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 bin or gnu - categories. + &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 bin or + gnu categories. @@ -163,38 +178,37 @@ but are instead part of the &os; Ports Collection (category ports). 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. + 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. - - 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. - - If the problem is in the base system, first read - the FAQ section on - - &os; versions, 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 + 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. + + If the problem is in the base system, first read the FAQ + section on &os; + versions, 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 list of supported - versions. + versions. 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. + with older version of applications simply cannot be + fixed.
@@ -210,24 +224,24 @@ - The &os; - Frequently Asked + The &os; Frequently Asked Questions (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 hardware compatibility, user - applications, - and kernel + applications, and + kernel configuration. - The - mailing - lists—if you are not subscribed, use - the + The mailing + lists—if you are not subscribed, use the searchable archives 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 @@ - Next, the searchable - - &os; PR database (GNATS). Unless the problem - is recent or obscure, there is a fair chance it has already - been reported. + Next, the searchable &os; + PR database (GNATS). Unless the problem is recent + or obscure, there is a fair chance it has already been + reported. Most importantly, attempt to see if existing - documentation in the source base addresses your problem. + documentation in the source base addresses your + problem. - For the base &os; code, you should - carefully study the contents of - /usr/src/UPDATING on your system - or the latest version at - http://svnweb.freebsd.org/base/head/UPDATING?view=log. - (This is vital information - if you are upgrading from one version to - another—especially if you are upgrading to the - &os.current; branch). - - However, if the problem is in something that was installed - as a part of the &os; Ports Collection, you should refer to - /usr/ports/UPDATING (for individual ports) - or /usr/ports/CHANGES (for changes - that affect the entire Ports Collection). - http://svnweb.freebsd.org/ports/head/UPDATING?view=log - and - http://svnweb.freebsd.org/ports/head/CHANGES?view=log + For the base &os; code, you should carefully study the + contents of /usr/src/UPDATING on your + system or the latest version at http://svnweb.freebsd.org/base/head/UPDATING?view=log. + (This is vital information if you are upgrading from one + version to another—especially if you are upgrading to + the &os.current; branch). + + However, if the problem is in something that was + installed as a part of the &os; Ports Collection, you should + refer to /usr/ports/UPDATING (for + individual ports) or /usr/ports/CHANGES + (for changes that affect the entire Ports Collection). http://svnweb.freebsd.org/ports/head/UPDATING?view=log + and http://svnweb.freebsd.org/ports/head/CHANGES?view=log are also available via svnweb. @@ -281,10 +294,10 @@ Writing the Problem Report 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.
@@ -293,10 +306,10 @@ Do not leave the Synopsis - line empty. The PRs go both onto a mailing list - that goes all over the world (where the Synopsis - is used - for the Subject: line), but also into a + line empty. The PRs go both onto a mailing + list that goes all over the world (where the + Synopsis is used for the + Subject: 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 @@ Avoid using a weak Synopsis - line. 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 Synopsis: portupgrade is - broken, see how much more informative this - seems: Synopsis: port ports-mgmt/portupgrade - coredumps on -current. (In the case of ports, - it is especially helpful to have both the category and - portname in the Synopsis line.) + line. 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 + Synopsis: portupgrade is broken, see + how much more informative this seems: + Synopsis: port ports-mgmt/portupgrade coredumps + on -current. (In the case of ports, it is + especially helpful to have both the category and portname + in the Synopsis line.) If you have a patch, say so. 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 [patch] (including the brackets) at the - beginning of the Synopsis. (Although it is - not mandatory to use that exact string, by convention, - that is the one that is used.) + looked at than one without. If you are including one, put + the string [patch] (including the + brackets) at the beginning of the Synopsis. + (Although it is not mandatory to use that exact string, by + convention, that is the one that is used.) If you are a maintainer, say so. If you are maintaining a part of the source code (for instance, a port), you might consider adding the string - [maintainer update] (including the brackets) at the beginning of - your synopsis line, and you definitely should set the - Class of - your PR to maintainer-update. This way - any committer that handles your PR will not have to check. + [maintainer update] (including the + brackets) at the beginning of your synopsis line, and you + definitely should set the Class of your PR + to maintainer-update. This way any + committer that handles your PR will not have to + check. - Be specific. - The more information you supply about what problem you - are having, the better your chance of getting a response. + Be specific. The more information + you supply about what problem you are having, the better + your chance of getting a response. 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 CD-ROM 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. + 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 + CD-ROM 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. Include which global options you have specified in your make.conf. Note: specifying -O2 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. + 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. 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. + 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. 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): + 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): your kernel configuration (including which hardware devices you have installed) + - whether or not you have debugging options enabled - (such as WITNESS), and if so, - whether the problem persists when you change the - sense of that option + whether or not you have debugging options + enabled (such as WITNESS), and + if so, whether the problem persists when you + change the sense of that option + - the full text of any backtrace, panic or other console - output, or entries in /var/log/messages, - if any were generated + the full text of any backtrace, panic or other + console output, or entries in + /var/log/messages, if any + were generated + - the output of pciconf -l and - relevant parts of your dmesg output if - your problem relates to a specific piece of hardware + the output of pciconf -l + and relevant parts of your + dmesg output if your problem + relates to a specific piece of hardware + the fact that you have read - src/UPDATING and that your problem - is not listed there (someone is guaranteed to ask) + src/UPDATING and that your + problem is not listed there (someone is guaranteed + to ask) + whether or not you can run any other kernel as a fallback (this is to rule out hardware-related @@ -435,52 +461,56 @@ which ports you have installed + any environment variables that override the defaults in bsd.port.mk, such as PORTSDIR + the fact that you have read - ports/UPDATING and that your problem - is not listed there (someone is guaranteed to ask) + ports/UPDATING and that your + problem is not listed there (someone is guaranteed + to ask) - - - Avoid vague requests for features. - PRs of the form someone should really implement something - that does so-and-so are less likely to get results than + Avoid vague requests for + features. PRs of the form + someone should really implement something that does + so-and-so 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 freebsd-questions - than an entry in the PR database, as discussed above. + topic for discussion on + freebsd-questions than an entry in the + PR database, as discussed above. Make sure no one else has already submitted - a similar PR. Although this has already been + a similar PR. 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 - http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query. + minute or two to use the web-based search engine at http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query. (Of course, everyone is guilty of forgetting to do this now and then.) Report only one issue per Problem - Report. Avoid including two or more problems + Report. 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. + fixing multiple bugs in the same PR unless they are + closely related—such PRs often take longer to + resolve. @@ -490,18 +520,18 @@ offer patches, but also justification for why the patches are The Right Thing To Do. As noted above, a careful search of the mailing lists using the archives - at http://www.FreeBSD.org/search/search.html#mailinglists + at http://www.FreeBSD.org/search/search.html#mailinglists is always good preparation. - Be polite. - 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. + Be polite. 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.
@@ -514,34 +544,35 @@ VISUAL is not set) environment variable is set to something sensible. - 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 Electronic - Mail chapter of the &os; Handbook at - http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html. + 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 Electronic Mail chapter of the &os; + Handbook at http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html. 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. + 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. Similar considerations apply to use of the web-based - PR submission form. 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. - - 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 web form. + PR submission form. 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. + + 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 + web + form.
@@ -556,48 +587,49 @@ command-line option to specify the names of the files you wish to attach: -&prompt.user; send-pr -a /var/run/dmesg -a /tmp/errors + &prompt.user; send-pr -a /var/run/dmesg -a /tmp/errors - Do not worry about binary files, they will be automatically - encoded so as not to upset your mail agent. + Do not worry about binary files, they will be + automatically encoded so as not to upset your mail + agent. When attaching a patch, be sure to use - or 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. + or 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. 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. + 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. Do not send patches as attachments using - Content-Transfer-Encoding: quoted-printable. - These will perform character escaping and the entire patch - will be useless. + Content-Transfer-Encoding: + quoted-printable. These will perform character + escaping and the entire patch will be useless. 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 closed. + 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 closed. You should also take note that unless you explicitly specify otherwise in your PR or in the patch itself, any @@ -610,12 +642,12 @@ The next section applies to the email method only: - &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. + &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. At the top of the template, below the SEND-PR: lines, are the email headers. You @@ -649,26 +681,25 @@ Severity: One of non-critical, - serious or - critical. Do not overreact; refrain - from labeling your problem critical - unless it really is (e.g., data corruption issues, serious - regression from previous functionality in -CURRENT) - or serious 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. + serious or critical. + Do not overreact; refrain from labeling your problem + critical unless it really is (e.g., + data corruption issues, serious regression from previous + functionality in -CURRENT) or serious + 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. Security problems should not - be filed in GNATS, because all GNATS information is public - knowledge. Please send such problems according to our - security + be filed in GNATS, because all GNATS information is + public knowledge. Please send such problems according + to our security report guidelines. @@ -691,28 +722,27 @@ The next section describes fields that are common to both - the email interface and the web interface: + the email interface and the + web + interface: - - Originator: - Please specify your real name, optionally followed - by your email address in angle brackets. - In the email interface, this is normally + Originator: Please specify your + real name, optionally followed by your email address in + angle brackets. In the email interface, this is normally prefilled with the gecos field of the - currently logged-in - user. + currently logged-in user. - 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. + 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. - @@ -729,90 +759,98 @@ summaries; problem reports with obscure synopses tend to get ignored. - As noted above, if your problem report includes a patch, - please have the synopsis start with [patch] (including the brackets); - if this is a ports PR and you are the - maintainer, you may consider adding - [maintainer update] (including the brackets) and set the - Class of your PR to - maintainer-update. + As noted above, if your problem report includes a + patch, please have the synopsis start with + [patch] (including the brackets); if + this is a ports PR and you are the maintainer, you may + consider adding [maintainer update] + (including the brackets) and set the Class + of your PR to maintainer-update. Category: Choose an appropriate category. - 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 base system). - 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 + 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 + base system). 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. Here is a description of the major categories: - If a problem is with the kernel, the libraries (such - as standard C library libc), or a - peripheral driver in the base system, in general you will - use the kern 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. + If a problem is with the kernel, the libraries + (such as standard C library libc), + or a peripheral driver in the base system, in general + you will use the kern 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. 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 - whereis programname. - &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 whereis + programname. + &os;'s convention for the Ports Collection is to + install everything underneath /usr/local, - although this can be overridden by a system administrator. - For these, you will use the ports - category (yes, even if the port's category is - www; see below). If the location is + although this can be overridden by a system + administrator. For these, you will use the + ports category (yes, even if the + port's category is www; see below). + If the location is /bin, /usr/bin, /sbin, or - /usr/sbin, - it is part of the base system, and you should use the - bin category. (A few programs, such as - &man.gcc.1;, actually use the gnu category, *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***