Comments?
>From d4c14591bed2ddb08b146a18693e83697ce9f45b Mon Sep 17 00:00:00 2001
From: John Darrington <[email protected]>
Date: Wed, 29 Oct 2014 16:22:05 +0100
Subject: [PATCH] Documentation: Add some comments to the bugs chapter
---
doc/bugs.texi | 75 +++++++++++++++++++++++++++++++++++++++++++++++---------
1 files changed, 63 insertions(+), 12 deletions(-)
diff --git a/doc/bugs.texi b/doc/bugs.texi
index 96c1ed2..e8ea6d2 100644
--- a/doc/bugs.texi
+++ b/doc/bugs.texi
@@ -2,35 +2,86 @@
@chapter Bugs
@cindex bugs
+@cindex troubleshooting
+
+Occasionally you may encounter a bug in @pspp{}.
+
+@section When to report bugs
-Occasionally users encounter problems with @pspp{}.
-When such problems arise we do our best to fix them, but our limited
-resources mean that certain issues may remain for some time.
If you discover a bug, please first:
@itemize @bullet
+@item Make sure that it really is a bug. Sometimes, what may appear
+to be a bug, turns out to be a misunderstanding of how to use the program.
@item Try an up to date version of @pspp{}; it may be that the problem
- has recently been fixed.
-@item If the problem persists in the up to date version; check to see
- if it has already been reported.
+ has recently been fixed.
+@item If the problem persists in the up to date version, check to see
+ if it has already been reported. Reported issues are listed
+ at @uref{http://savannah.gnu.org/bugs/?group=pspp}.
+ For known issues in individual language features, see the relevant section in
@pxref{Language}.
@item If the problem exists in a recent version and it has not already
- been reported, please file a report.
+ been reported, then please file a report.
@end itemize
-To see a list of reported bugs, visit @pspp{}'s project webpage at
-@uref{http://savannah.gnu.org/bugs/?group=pspp}
+
+@section How to report bugs
+
+The best way to send a bug report is using the web page at
+@uref{http://savannah.gnu.org/bugs/?group=pspp}.
Alternatively, bug reports may be sent by email
to @email{bug-gnu-pspp@@gnu.org}.
In your bug report please include:
@itemize @bullet
-@item The version of @pspp{} which you are using.
+@item The version of @pspp{} in which you encountered the problem.
+That means the precise version number. Do not simply say ``the latest
version'' --- that is of little
+help to the developers.
@item The operating system and type of computer on which it is running.
@item A sample of the syntax which causes the problem or, if it is a user
interface problem, the sequence of steps required to reproduce it.
+ Screen shots are not usually helpful unless you are reporting a bug in
+ the graphical user interface itself.
@item A description of what you think is wrong: What happened that you
didn't expect, and what did you expect to happen?
@end itemize
-For known bugs in individual language features, see the documentation
-for that feature.
+The following is an example of a useful bug report:
+@example
+Running PSPP 0.8.4 on GNU/Linux mips64 --- Running the following
+syntax:
+
+DATA LIST FREE /x *.
+BEGIN DATA.
+1 2 3
+END DATA.
+LIST.
+
+results in:
+
+4
+5
+6
+
+I think the output should be:
+
+1
+2
+3
+@end example
+@noindent Here, the developers have the necessary information to reproduce the
circumstances of the bug report,
+and they understand what the reporter expected.
+
+
+Conversely, the following is a useless bug report:
+
+@example
+I downloaded the latest version of PSPP and entered a sequence of numbers,
+but when I print them out it gives the wrong output.
+@end example
+@noindent In that example, it is impossible to reproduce, and there is no
indication
+of why the reporter thought what he saw was wrong.
+Note that the purpose of bug reports is to help improve the quality of @pspp{}
+for the benefit of all users.
+Please do not use the bug reporting address for general enquiries or to seek
+help in using, installing or running the program.
+For that, use the email address @email{pspp-users@@gnu.org}.
--
1.7.2.5
_______________________________________________
pspp-dev mailing list
[email protected]
https://lists.gnu.org/mailman/listinfo/pspp-dev
