+@c PSPP - a program for statistical analysis.
+@c Copyright (C) 2017 Free Software Foundation, Inc.
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3
+@c or any later version published by the Free Software Foundation;
+@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
+@c A copy of the license is included in the section entitled "GNU
+@c Free Documentation License".
+@c
@node Bugs
@chapter Bugs
@cindex bugs
+@cindex troubleshooting
-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 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.
-@item If the problem exists in a recent version and it has not already
- been reported, please file a report.
-@end itemize
+Occasionally you may encounter a bug in @pspp{}.
+
+If you believe you have found a bug, please
+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.
+If you are unsure, ask for advice on the pspp-users mailing list.
+Information about the mailing list is at @uref{http://lists.gnu.org/mailman/listinfo/pspp-users}.
+
+It is also valuable to try the newest version of @pspp{}, since the
+problem may have already been fixed. You can always find the newest
+version of PSPP by visiting @url{https://www.gnu.org/s/pspp, the PSPP
+website}. You might have obtained PSPP from a downstream packager,
+such as a GNU/Linux distribution; if your downstream package is not
+up-to-date, please ask the distributor to update to the newest
+version.
+
+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}. If it has already
+been reported, you might consider adding a comment with additional
+information or even just to mention that you are also experiencing the
+problem, since the PSPP developers are often inclined to work on
+issues that are important to a large number of users.
-To see a list of reported bugs, visit @pspp{}'s project webpage at
-@uref{http://savannah.gnu.org/bugs/?group=pspp}
+ For known issues in individual language features, see the relevant section in @pxref{Language}.
+
+If the problem exists in a recent version and it has not already
+been reported, then please report it.
+
+
+@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:
+A high-quality bug report allows the developers to understand,
+reproduce, and ultimately fix the problem. We recommend
+including the following:
@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. ``The latest version''
+is often too ambiguous because
+releases happen quickly, and bug reports are archived indefinitely.
@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.
-@item A description of what you think is wrong: What happened that you
+ Screenshots can be helpful for reporting bugs in the graphical user
+ interface, especially since GUI bugs can arise on some systems but
+ not others, but they do not usually help fixing other kinds of bugs.
+@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.
+Here is one example of a bug report that includes all of the elements above:
+
+@cartouche
+@example
+When I run PSPP 0.8.4 on my GNU/Linux system, executing the following
+syntax:
+
+ DATA LIST FREE /x *.
+ BEGIN DATA.
+ 1 2 3
+ END DATA.
+ LIST.
+
+results in:
+
+ 4
+ 5
+ 6
+
+but I think the output should be:
+
+ 1
+ 2
+ 3
+@end example
+@end cartouche
+
+The following bug report, on the other hand, does not provide enough
+information for PSPP developers to understand the problem. This means
+that the developers cannot identify or fix the problem without
+additional rounds of questions, which is more work for both the
+reporter and the developer:
+
+@cartouche
+@example
+I downloaded the latest version of PSPP and entered a sequence of numbers,
+but when I analyse them it gives the wrong output.
+@end example
+@end cartouche
+
+@pspp{} developers value all users' feedback, but cannot promise
+an immediate response. The bug reporting is not a consultancy or
+support service, although you can make private arrangements for such
+services. Since @pspp{} is free software, consultants have access to
+the information they need to provide such support.
+
+For general enquiries or help, please use the
+@uref{http://lists.gnu.org/mailman/listinfo/pspp-users, pspp-users
+mailing list} instead of the bug mailing list or bug tracker.
+The PSPP bug tracker and bug reporting mailing list are public. To
+privately report a security vulnerability in GNU PSPP, please send
+your report to the closed mailing list @email{pspp-security@@gnu.org}.
+The PSPP developers will help you assess your report and fix problems
+prior to public disclosure.
projects / pspp / blobdiff