maint: improve `Reporting Bugs' in README and README.alpha.

* README (Reporting Bugs): Rewritten to a more complete and
concise guide to providing a good bug report.
* README.alpha (Reporting Bugs): Adjust to match.

Signed-off-by: Gary V. Vaughan <gary@gnu.org>

diff --git a/ChangeLog b/ChangeLog
index da2247382e2c3fbeb8506ceb5e3cf773087aa1ca..ea2ac0897cbe40e97eaef5f603a63fcc6d8e21d5 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -6,6 +6,11 @@
 
 2010-09-18  Gary V. Vaughan  <gary@gnu.org>
 
+       maint: improve `Reporting Bugs' in README and README.alpha.
+       * README (Reporting Bugs): Rewritten to a more complete and
+       concise guide to providing a good bug report.
+       * README.alpha (Reporting Bugs): Adjust to match.
+
        maint: consolidate Introductions of README and README.alpha.
        * README (Introduction): Rewritten to a more logical order for
        first time users, incorporating some additional text that was

diff --git a/README b/README
index c2e83f1e965510a9bc0398a3d52e32205689abf6..ab61b48716d0db858bd8fef058bad13712b75c82 100644 (file)
--- a/README
+++ b/README
@@ -41,11 +41,37 @@ details.
 2. Reporting Bugs
 =================
 
-If you have any suggestions or bug reports, or you wish to port Libtool
-to a new platform, please send electronic mail to the libtool mailing
-list <libtool@gnu.org> or bug reports to <bug-libtool@gnu.org>.  Be sure
-to send us your information from the end of the help message given by
-`./libtool --help'.
+If this distribution doesn't work for you, before you report the
+problem, at least try upgrading to the latest released version first,
+and see whether the issue persists.  If you feel able, you can also
+check whether the issue has been fixed in the development sources for
+the next release (see `Obtaining the Latest Sources' below).
+
+Once you've determined that your bug is still not fixed in the latest
+version, please send a full report to <bug-libtool@gnu.org>, including:
+
+  1. the information from the end of the help message given by
+     `./libtool --help', and the verbose output of any failed tests
+     (see `The Test Suites' immediately below);
+  2. complete instructions for how to reproduce your bug, along with
+     the results you were expecting, and how they differ from what you
+     actually see;
+  3. a workaround or full fix for the bug, if you have it;
+  4. a copy of `tests/testsuite.log' if you are experiencing failures
+     in the Autotest testsuite.
+  5. new test cases for the testsuite that demonstrate the bug are
+     especially welcome, and will help to ensure that future releases
+     don't reintroduce the problem - if you're not able to write a
+     complete testsuite case, a simple standalone shell script is
+     usually good enough to help us write a test for you.
+
+If you have any other suggestions, or if you wish to port Libtool to a
+new platform, please send email to the mailing list <libtool@gnu.org>.
+
+Please note that if you send us an non-trivial code for inclusion in a
+future release, we may ask you for a copyright assignment (for brief
+details see the `Copyright Assignment' section on our `Contributing'
+webpage <http://www.gnu.org/software/libtool/contribute.html>).
 
 
 3. The Test Suites

diff --git a/README.alpha b/README.alpha
index d7d271872873a31a325212a57e784f9c5db05c7a..a651b49673aed74d39bb286869ab1d92fc380725 100644 (file)
--- a/README.alpha
+++ b/README.alpha
@@ -42,20 +42,36 @@ details.
 =================
 
 If this distribution doesn't work for you, before you report the
-problem, please try upgrading to the latest version first (see
-`Obtaining the latest sources' below).
-
-The `bootstrap' script sets up the source directory for you to hack,
-though it may take quite some time to run.  If you don't intend to
-re-run the test suite, you can speed up the `bootstrap' step by an
-order of magnitude if you call it like this instead:
-
-  reconfdirs='. libltdl' ./bootstrap
-
-If your bug is still not fixed in the latest version, please send a full
-report to <bug-libtool@gnu.org>, including the information from the end
-of the help message given by `./libtool --help', and the verbose output
-of any failed test groups (as described below).
+problem, at least try upgrading to the latest released version first,
+and see whether the issue persists.  If you feel able, you can also
+check whether the issue has been fixed in the development sources for
+the next release (see `Obtaining the Latest Sources' below).
+
+Once you've determined that your bug is still not fixed in the latest
+version, please send a full report to <bug-libtool@gnu.org>, including:
+
+  1. the information from the end of the help message given by
+     `./libtool --help', and the verbose output of any failed tests
+     (see `The Test Suites' immediately below);
+  2. complete instructions for how to reproduce your bug, along with
+     the results you were expecting, and how they differ from what you
+     actually see;
+  3. a workaround or full fix for the bug, if you have it;
+  4. a copy of `tests/testuite.log' if you are experiencing failures
+     in the Autotest testsuite.
+  5. new test cases for the testsuite that demonstrate the bug are
+     especially welcome, and will help to ensure that future releases
+     don't reintroduce the problem - if you're not able to write a
+     complete testsuite case, a simple standalone shell script is
+     usually good enough to help us write a test for you.
+
+If you have any other suggestions, or if you wish to port Libtool to a
+new platform, please send email to the mailing list <libtool@gnu.org>.
+
+Please note that if you send us an non-trivial code for inclusion in a
+future release, we may ask you for a copyright assignment (for brief
+details see the `Copyright Assignment' section on our `Contributing'
+webpage <http://www.gnu.org/software/libtool/contribute.html>).
 
 
 3. The Test Suites