From owner-freebsd-doc@FreeBSD.ORG Mon Apr 11 03:56:49 2005 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 633B816A4CE for ; Mon, 11 Apr 2005 03:56:49 +0000 (GMT) Received: from mail.soaustin.net (mail.soaustin.net [207.200.4.66]) by mx1.FreeBSD.org (Postfix) with ESMTP id AB6B543D3F for ; Mon, 11 Apr 2005 03:56:48 +0000 (GMT) (envelope-from linimon@lonesome.com) Received: by mail.soaustin.net (Postfix, from userid 502) id 139541492B; Sun, 10 Apr 2005 22:56:48 -0500 (CDT) Date: Sun, 10 Apr 2005 22:56:48 -0500 (CDT) From: Mark Linimon X-X-Sender: linimon@pancho To: freebsd-doc@FreeBSD.org Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Subject: CFD: additions to the PR submission article X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.1 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 11 Apr 2005 03:56:49 -0000 As part of my work on bugmeister I keep encountering the same problems with PR submissions over and over. This proposed patch makes the following changes: - further clarifies the distinction between software written by FreeBSD contributors and software written by others - defines when code is too old to file a PR against - adds text about mangled formatting, especially by mailers Unless there are any objections I intend to commit these changes once the freeze is lifted. Thanks, mcl Index: article.sgml =================================================================== RCS file: /home/FreeBSD/dcvs/doc/en_US.ISO8859-1/articles/problem-reports/article.sgml,v retrieving revision 1.36 diff -u -r1.36 article.sgml --- article.sgml 15 Jan 2005 02:16:42 -0000 1.36 +++ article.sgml 11 Apr 2005 03:53:25 -0000 @@ -104,20 +104,11 @@ Notification of updates to externally maintained - software (mainly ports, but also externally maintained base - system components such as BIND or various GNU - utilities). + software (see below). - Another thing is that if the system on which you experienced - the bug is not fairly up-to-date, you should seriously consider - upgrading and trying to reproduce the problem on an up-to-date - system before submitting a problem report. There are few things - that will annoy a developer more than receiving a problem report - about a bug she has already fixed. - - Finally, a bug that can not be reproduced can rarely be + Note that 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 @@ -127,6 +118,71 @@ 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); + 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. + + + + 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. + + + + Individual applications that are not in the base system + 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, you + should only report a problem to the &os; developers when you + believe the problem is &os;-specific; otherwise, you should + report it to the authors of the software. + + + + + Then you should ascertain whether or not 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, you should 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. + + 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 + anything other than the absolute latest versions, and problems + with older version of applications simply cannot be fixed.
@@ -209,25 +265,6 @@ are also available via CVSweb. - - Next, you need to make sure your problem report goes to the - right people. - - The first catch here is that if the problem is a bug in - third-party software (a port or a package you have installed), you - should report the bug to the original author, not to the &os; - Project. There are two exceptions to this rule: the first is if - the bug does not occur on other platforms, in which case the - problem may lie in how the software was ported to &os;; the - second is if the original author has already fixed the bug and - released a patch or a new version of his software, and the - &os; port has not been updated yet. - - The second catch is that &os;'s bug tracking system sorts - problem reports according to the category the originator - selected. Therefore, if you select the wrong category when you - submit your problem report, there is a good chance that it will - go unnoticed for a while, until someone re-categorizes it.
@@ -434,7 +471,7 @@
Before you begin - Before running the &man.send-pr.1; program, make sure your + If you are using the &man.send-pr.1; program, make sure your VISUAL (or EDITOR if VISUAL is not set) environment variable is set to something sensible. @@ -447,6 +484,24 @@ on the setup of mail on &os;, see the Electronic Mail chapter of the &os; Handbook at . + + Make sure that your mailer will not mangle the message on + its way to GNATS. In particular, if your mailer automatically + breaks lines, changes tabs to spaces, or escapes newline + characters, any patch that you submit will be rendered + unusable. For the text sections, however, we request that + you insert manual linebreaks somewhere around 70 characters, + so that the web display of the PR will be readable. + + Similar considerations apply if you are using the web-based + PR submittal form instead of &man.send-pr.1;. 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 your submission will be lengthy, you may wish + to prepare your work offline so that nothing will be lost in + case there is a problem in transmission.
@@ -492,7 +547,10 @@ 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. + 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