pivot-table: Make PIVOT_N_AXES a macro instead of an enum.
[pspp] / doc / bugs.texi
1 @c PSPP - a program for statistical analysis.
2 @c Copyright (C) 2017, 2020 Free Software Foundation, Inc.
3 @c Permission is granted to copy, distribute and/or modify this document
4 @c under the terms of the GNU Free Documentation License, Version 1.3
5 @c or any later version published by the Free Software Foundation;
6 @c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
7 @c A copy of the license is included in the section entitled "GNU
8 @c Free Documentation License".
9 @c
10 @node Bugs
11 @chapter Bugs
12
13 @cindex bugs
14 @cindex troubleshooting
15
16 Occasionally you may encounter a bug in @pspp{}.
17
18 If you believe you have found a bug, please
19 make sure that it really is a bug.  Sometimes, what may appear
20 to be a bug, turns out to be a misunderstanding of how to use the program.
21 If you are unsure, ask for advice on the pspp-users mailing list.
22 Information about the mailing list is at @uref{http://lists.gnu.org/mailman/listinfo/pspp-users}.
23
24 It is also valuable to try the newest version of @pspp{}, since the
25 problem may have already been fixed.  You can always find the newest
26 version of PSPP by visiting @url{https://www.gnu.org/s/pspp, the PSPP
27 website}.  You might have obtained PSPP from a downstream packager,
28 such as a GNU/Linux distribution; if your downstream package is not
29 up-to-date, please ask the distributor to update to the newest
30 version.
31
32 If the problem persists in the up-to-date version, check to see if it
33 has already been reported.  Reported issues are listed at
34 @uref{http://savannah.gnu.org/bugs/?group=pspp}.  If it has already
35 been reported, you might consider adding a comment with additional
36 information or even just to mention that you are also experiencing the
37 problem, since the PSPP developers are often inclined to work on
38 issues that are important to a large number of users.
39
40  For known issues in individual language features, see the relevant section in @pxref{Language}.
41
42 If the problem exists in a recent version and it has not already
43 been reported, then please report it.
44
45
46 @section How to report bugs
47
48 The best way to send a bug report is using the web page at
49 @uref{http://savannah.gnu.org/bugs/?group=pspp}.
50 Alternatively, bug reports may be sent by email
51 to @email{bug-gnu-pspp@@gnu.org}.
52
53 A high-quality bug report allows the developers to understand,
54 reproduce, and ultimately fix the problem.  We recommend
55 including the following:
56
57 @itemize @bullet
58 @item
59 The version of @pspp{} in which you encountered the problem.  It also
60 often helps to know some information about how @pspp{} was built.
61
62 With @pspp{} command syntax, @code{SHOW SYSTEM.} will output
63 everything we ordinarily need.  In the PSPPIRE GUI,
64 @clicksequence{Help @click{} System Info} produces the same output.
65
66 @item The operating system and type of computer on which it is running.
67
68 @item A sample of the syntax which causes the problem or, if it is a user
69  interface problem, the sequence of steps required to reproduce it.
70  Screenshots can be helpful for reporting bugs in the graphical user
71  interface, especially since GUI bugs can arise on some systems but
72  not others, but they do not usually help fixing other kinds of bugs.
73
74 @item A description of what you think is wrong: What happened that you
75   didn't expect, and what did you expect to happen?  Include any error
76   messages that @pspp{} output.
77 @end itemize
78
79 Here is one example of a bug report that includes all of the elements above:
80
81 @cartouche
82 @example
83 I'm running PSPP on a system where @code{SHOW SYSTEM.}  outputs the
84 following:
85
86 @psppoutput{show-system}
87
88 The bug I'm seeing is that executing the following syntax:
89
90  DATA LIST FREE /x *.
91  BEGIN DATA.
92  1 2 3
93  END DATA.
94  LIST.
95
96 results in:
97
98  4
99  5
100  6
101
102 but I think the output should be:
103
104  1
105  2
106  3
107 @end example
108 @end cartouche
109
110 The following bug report, on the other hand, does not provide enough
111 information for PSPP developers to understand the problem.  This means
112 that the developers cannot identify or fix the problem without
113 additional rounds of questions, which is more work for both the
114 reporter and the developer:
115
116 @cartouche
117 @example
118 I downloaded the latest version of PSPP and entered a sequence of numbers,
119 but when I analyse them it gives the wrong output.
120 @end example
121 @end cartouche
122
123 @pspp{} developers value all users' feedback, but cannot promise
124 an immediate response.  The bug reporting is not a consultancy or
125 support service, although you can make private arrangements for such
126 services.  Since @pspp{} is free software, consultants have access to
127 the information they need to provide such support.
128
129 For general enquiries or help, please use the
130 @uref{http://lists.gnu.org/mailman/listinfo/pspp-users, pspp-users
131 mailing list} instead of the bug mailing list or bug tracker.
132
133 The PSPP bug tracker and bug reporting mailing list are public.  To
134 privately report a security vulnerability in GNU PSPP, please send
135 your report to the closed mailing list @email{pspp-security@@gnu.org}.
136 The PSPP developers will help you assess your report and fix problems
137 prior to public disclosure.