Mercurial > web-octave

comparison bugs.md @ 193:8ec5df986ad3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
* bugs.md: Overhaul page.
author Kai T. Ohlhus <k.ohlhus@gmail.com>
date Wed, 08 Jul 2020 15:16:23 +0900
parents 527e9231e4ff
children 9d652d8ece7c
comparison
equal deleted inserted replaced
192:c8dba4c0fd04 193:8ec5df986ad3
1 --- 1 ---
2 layout: page 2 layout: page
3 title: Bugs 3 title: Bugs
4 menu: false 4 menu: true
5 --- 5 ---
6 6
7 GNU Octave uses the bug tracker at [Savannah][1]. 7 GNU Octave uses the bug tracker at [Savannah]({{ site.bugs_url }}).
8 There you can [report a new bug][2], [browse recent bugs][1], 8 There you can [report a new bug]({{ site.bugs_url }}&func=additem),
9 or [search for bugs][3]. 9 [browse recent bugs]({{ site.bugs_url }}),
10 or [search for bugs]({{ site.bugs_url }}&func=search).
10 11
11 [1]: {{ site.bugs_url }} 12 ### Guidelines for reporting a new bug
12 [2]: {{ site.bugs_url }}&func=additem
13 [3]: {{ site.bugs_url }}&func=search
14 13
15 <div class="row"> 14 1. **Is the bug already known?**
16 <div class="columns small-12">
17 <div class="panel callout">
18 Please do <strong>not</strong> send any bug reports to the
19 <samp>{{ site.help_email }}</samp> mailing list.
20 Most Octave users do not want to receive bug reports.
21 </div>
22 </div>
23 </div>
24 15
25 <div class="row "> 16 - [Search for already reported bugs at the bug tracker]({{ site.bugs_url }}&func=search),
26 <div class="columns small-12"> 17 - look at the
27 <div class="panel callout"> 18 [list of known causes of trouble]({{ site.docs_url }}/Trouble.html)
28 <strong>Before</strong> reporting a new bug, please read the guidelines below. 19 in the Octave manual.
29 </div> 20
30 </div> 21 <p></p>
31 </div> 22
23 If you your problem **does not appear** to be known,
24 then you should report the problem.
25
26 2. **Is it really a bug?**
27
28 - If Octave **crashes**, for any input whatever, that is a bug.
29 Reliable interpreters never crash.
30 - If Octave produces **incorrect results**, for any input whatever,
31 that is a bug.
32 - If Octave produces an **error message** for **valid input**, that is a bug.
33 - If Octave produces **no error message** for **invalid input**,
34 that is a bug.
35
36 <p></p>
37
38 3. **Make your bug report count**
39
40 - **Report all the facts:**<br>
41 Include all information that make it possible to fix the bug.
42 If you are not sure whether to state a fact or leave it out, state it.
43 This information includes your **operating system**, **Octave version**,
44 **exact error message** or **exact output**.
45 - **Give a short, specific, complete example:**<br>
46 Avoid: pseudocode, uninitialized variables,
47 calls to unattached scripts or functions.
48 - **Justify your exectations briefly:**<br>
49 Although it might seem obvious to you,
50 someone examining the problem might not know what result you consider
51 correct.
32 52
33 53
54 ### Sending Patches for Octave
34 55
35 # Is the bug already known? 56 If you have a suggested fix for a bug,
36 57 please attach it to your report in the tracker.
37 When you encounter a problem, 58 Your patch is more likely to be reviewed if you follow the guidelines from the
38 the first thing to do is to see if it is already known. 59 Octave Wiki about the [creation of changesets]({{ site.wiki_url }}/Mercurial).
39 Therefore,
40
41 - [search for already reported bugs at the bug tracker][3],
42
43 - look at the [list of known causes of trouble][4] in the Octave manual.
44
45 If you your problem does not appear to be known,
46 then you should report the problem.
47
48 Reporting a bug may help you by bringing a solution to your problem,
49 or it may not. In any case, the principal function of a bug report is
50 to help the entire community by making the next version of Octave work
51 better, so you can contribute to the maintenance of Octave.
52
53 [4]: {{ site.docs_url }}/Trouble.html#Trouble
54
55
56
57 # Is it really a bug?
58
59 If you are not sure whether you have found a bug, here are some guidelines:
60
61 - If Octave gets a fatal signal, for any input whatever, that is a bug.
62 Reliable interpreters never crash.
63
64 - If Octave produces incorrect results, for any input whatever, that is a bug.
65
66 - Some output may appear to be incorrect when it is in fact due to a
67 program whose behavior is undefined, which happened by chance to give
68 the desired results on another system. For example, trigonometric
69 functions may produce different results because of differences in the
70 math library or the way floating point arithmetic is handled on various
71 systems.
72
73 - If Octave produces an error message for valid input, that is a bug.
74
75 - If Octave does not produce an error message for invalid input, that is
76 a bug. However, you should note that your idea of "invalid input"
77 might be my idea of "an extension" or "support for traditional practice".
78
79 - If you are an experienced user of programs like Octave, your
80 suggestions for improvement are welcome in any case.
81
82
83
84 # Make your bug report count
85
86 In order for a bug report to serve its purpose, you must include the
87 information that makes it possible to fix the bug.
88
89 The fundamental principle of reporting bugs usefully is this:
90 **report all the facts**. If you are not sure whether to
91 state a fact or leave it out, state it.
92
93 Often people omit facts because they think they know what causes the
94 problem and they conclude that some details don't matter. Thus, you
95 might assume that the name of the variable you use in an example does
96 not matter. Well, probably it doesn't, but one cannot be sure.
97 Perhaps the bug is a stray memory reference which happens to fetch
98 from the location where that name is stored in memory; perhaps, if the
99 name were different, the contents of that location would fool the
100 interpreter into doing the right thing despite the bug. Play it safe
101 and give a specific, complete example.
102
103 Keep in mind that the purpose of a bug report is to enable someone to
104 fix the bug if it is not known. Always write your bug reports on
105 the assumption that the bug is not known.
106
107 Sometimes people give a few sketchy facts and ask, "Does this ring a
108 bell?" This cannot help us fix a bug. It is better to send a complete
109 bug report to begin with.
110
111 Try to make your bug report self-contained. If we have to ask you for
112 more information, it is best if you include all the previous information
113 in your response, as well as the information that was missing.
114
115 The bug tracker will prompt you for some basic information like
116 the version of Octave and the operating system you are using. You
117 also need to include the following to enable someone to
118 investigate the bug:
119
120 - A complete input file that will reproduce the bug.
121
122 A single statement may not be enough of an example--the bug might
123 depend on other details that are missing from the single statement where
124 the error finally occurs.
125
126 - The command arguments you gave Octave to execute that example
127 and observe the bug. To guarantee you won't omit something important,
128 list all the options.
129
130 If we were to try to guess the arguments, we would probably guess wrong
131 and then we would not encounter the bug.
132
133 - A description of what behavior you observe that you believe is incorrect.
134 For example, "The interpreter gets a fatal signal," or, "The output produced
135 at line 208 is incorrect."
136
137 - The output you expected to see. Although it might seem obvious to you,
138 someone examining the problem might not know what result you consider
139 correct.
140
141 - If you wish to suggest changes to the Octave source, send them as context
142 diffs. If you discuss something in the Octave source, refer to it by
143 context, not by line number, because the line numbers in the development
144 sources probably won't match those in your sources.
145
146
147
148 # Sending Patches for Octave
149
150 If you have a suggested fix for a bug, please attach it to your report in
151 the tracker. Your patch is more likely to be reviewed if you follow the
152 guidelines from the Octave Wiki about the [creation of changesets][5]
153 and submit patches for Octave.
154
155 [5]: {{ site.wiki_url }}/Mercurial#Submitting_patches