From 3cb0ed22ac75d5f4f675c83bad7290d9e88ab0ab Mon Sep 17 00:00:00 2001 From: Mark Linimon Date: Sun, 23 May 2004 22:32:55 +0000 Subject: [PATCH] Rewrite the section on what information needs to be supplied to make a good Problem Report. Add pointers to the new files ports/CHANGES and ports/UPDATING. Change some occurrences of FreeBSD to &os; if they were in the affected lines (another commit will do the remaining ones). Suggest guidelines for the often-abused Severity and Priority fields. Add a pointer to the categories definition file. Add the 'threads' category. Add a warning to include the tracking number on followups to save creating new, bogus, PRs. PR: docs/67062 Reviewed by: ceri, keramida, others Approved by: ceri (mentor) --- .../articles/problem-reports/article.sgml | 201 +++++++++++++++--- 1 file changed, 166 insertions(+), 35 deletions(-) diff --git a/en_US.ISO8859-1/articles/problem-reports/article.sgml b/en_US.ISO8859-1/articles/problem-reports/article.sgml index a59c26c8ac..75ad974a51 100644 --- a/en_US.ISO8859-1/articles/problem-reports/article.sgml +++ b/en_US.ISO8859-1/articles/problem-reports/article.sgml @@ -5,6 +5,8 @@ %mailing-lists; %trademarks; + +%freebsd; ]>
@@ -125,8 +127,10 @@ 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, and you should consider letting the - matter drop. + 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.
@@ -185,14 +189,26 @@ - Finally, if you are upgrading from one version to - another—especially if you are upgrading to the - -current branch—you should + Most importantly, you should attempt to see if existing + documentation in the source base addresses your problem. + + For the base &os; code, you should carefully study the contents of the /usr/src/UPDATING file on your system or its latest version at . - This file contains many pieces of vital information. + (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). + and + are also available via CVSweb. @@ -274,31 +290,102 @@ If you are maintaining a part of the source code (for instance, a port), you might consider adding the string [maintainer update] at the beginning of - your synopsis line and/or set the Class 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 - with the Makefile of the PR every - time the PR is viewed to make sure this is an update sent - by the maintainer of the port. + 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. - You should include such things as what version you are - running (there is a place to put that, see below); - which architecture you are running on; - whether you are running from a release CDROM, or from - a system maintained by &man.cvsup.1; (and, if so, how - recently you updated); and, if a kernel problem, - if you have read src/UPDATING - (someone is guaranteed to ask). You do not necessarily - have to provide your kernel configuration, which ports - you have available, and a core dump (including these - by default only tends to fill up the database), but you - should be prepared to make them available, either - privately or publicly, if so asked. + 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 CDROM or download), or from + a system maintained by &man.cvsup.1; (and, if so, how + recently you updated). 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. + + + + 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): + + + + 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 + + + a backtrace, if one was generated + + + the fact that you have read + 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 + issues such as failing disks and overheating CPUs, + which can masquerade as kernel problems) + + + + + + If this is a ports 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): + + + + 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) + + + + + @@ -384,8 +471,9 @@ preferred), and make sure to specify the exact CVS revision numbers of the files you modified so the developers who read your report will be - able to apply them easily. A patch against the CURRENT or HEAD - CVS branch is preferred since all new code should be applied + able to apply them easily. For problems with the kernel or the + base utilities, a patch against &os.current; (the HEAD + CVS 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 STABLE branch. @@ -476,7 +564,7 @@ As noted above, if your problem report includes a patch, please have the synopsis start with [patch]; if you are a maintainer, you may consider adding - [maintainer update] and/or set the + [maintainer update] and set the Class of your PR to maintainer-update. @@ -488,20 +576,29 @@ critical. Do not overreact; refrain from labeling your problem critical unless it really is (e.g. root exploit, easily - reproducible panic). Developers tend to ignore this and - the next field, precisely because problem report - submitters tend to overrate their problems. + reproducible panic) or serious unless + it is something that will affect many users (problems with + particular device drivers or system utilities). &os; + developers will not neccesarily 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, and the next, + because of this. Priority: One of low, medium or - high. See above. + high. high should + be reserved for problems that will affect practically + every user of &os; and medium for + something that will affect many users. Category: Choose one of the - following: + following (taken from + /usr/gnats/gnats-adm/categories): advocacy: problems relating to @@ -555,7 +652,7 @@ kern: problems with - kernel. + the kernel or (non-platform-specific) device drivers. @@ -584,6 +681,11 @@ issues. + + threads: problems related to the + &os; threads implementation (especially on &os.current;). + + www: Changes or enhancements to the FreeBSD website. @@ -712,11 +814,40 @@ If someone requests additional information from you, or you remember or discover something you did not mention in the - initial report, just mail it to + initial report, please use one of two methods to submit your + followup: + + + + The easiest way is to use the followup link on + the individual PR's web page, which you can reach from the + + PR search page. Clicking on this link will bring up an + an email window with the correct To: and Subject: lines filled in + (if your browser is configured to do this). + + + + Alternatively, you can just mail it to bug-followup@FreeBSD.org, making sure that the tracking number is included in the subject so the bug tracking system will know what problem report to attach it to. + + If you do not include the tracking + number, GNATS will become confused and create an entirely + new PR which it then assigns to the GNATS administrator, + and then your followup will become lost until someone + comes in to clean up the mess, which could be days or + weeks afterwards. + + Wrong way: Subject: that PR I sent + Right way: Subject: Re: ports/12345: compilation problem with foo/bar + + + + + If the problem report remains open after the problem has gone away, just send a follow-up (in the manner prescribed above) saying that the problem report can be closed, and, if