1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
<!DOCTYPE html>
<html>
<!-- Created by GNU Texinfo 7.1.1, https://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Bug Reporting (GNU Octave (version 10.3.0))</title>
<meta name="description" content="Bug Reporting (GNU Octave (version 10.3.0))">
<meta name="keywords" content="Bug Reporting (GNU Octave (version 10.3.0))">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta name="viewport" content="width=device-width,initial-scale=1">
<link href="index.html" rel="start" title="Top">
<link href="Concept-Index.html" rel="index" title="Concept Index">
<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="Reporting-Bugs.html" rel="up" title="Reporting Bugs">
<link href="Sending-Patches.html" rel="next" title="Sending Patches">
<link href="Bug-Tracker.html" rel="prev" title="Bug Tracker">
<style type="text/css">
<!--
a.copiable-link {visibility: hidden; text-decoration: none; line-height: 0em}
span:hover a.copiable-link {visibility: visible}
ul.mark-bullet {list-style-type: disc}
-->
</style>
<link rel="stylesheet" type="text/css" href="octave.css">
</head>
<body lang="en">
<div class="appendixsubsec-level-extent" id="Bug-Reporting">
<div class="nav-panel">
<p>
Next: <a href="Sending-Patches.html" accesskey="n" rel="next">Sending Patches for Octave</a>, Previous: <a href="Bug-Tracker.html" accesskey="p" rel="prev">Where to Report Bugs</a>, Up: <a href="Reporting-Bugs.html" accesskey="u" rel="up">Reporting Bugs</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<h4 class="appendixsubsec" id="How-to-Report-Bugs"><span>D.2.3 How to Report Bugs<a class="copiable-link" href="#How-to-Report-Bugs"> ¶</a></span></h4>
<a class="index-entry-id" id="index-bugs_002c-reporting-1"></a>
<p>Submit bug reports for Octave to the Octave bug tracker
<a class="url" href="https://bugs.octave.org">https://bugs.octave.org</a>.
</p>
<p>The fundamental principle of reporting bugs usefully is this:
<strong class="strong">report all the facts</strong>. If you are not sure whether to state a
fact or leave it out, state it!
</p>
<p>Often people omit facts because they think they know what causes the
problem and they conclude that some details don’t matter. Thus, you might
assume that the name of the variable you use in an example does not matter.
Well, probably it doesn’t, but one cannot be sure. Perhaps the bug is a
stray memory reference which happens to fetch from the location where that
name is stored in memory; perhaps, if the name were different, the contents
of that location would fool the interpreter into doing the right thing
despite the bug. Play it safe and give a specific, complete example.
</p>
<p>Keep in mind that the purpose of a bug report is to enable someone to
fix the bug if it is not known. Always write your bug reports on
the assumption that the bug is not known.
</p>
<p>Sometimes people give a few sketchy facts and ask, “Does this ring a
bell?” This cannot help us fix a bug. It is better to send a complete
bug report to begin with.
</p>
<p>Try to make your bug report self-contained. If we have to ask you for
more information, it is best if you include all the previous information
in your response, as well as the information that was missing.
</p>
<p>To enable someone to investigate the bug, you should include all these
things:
</p>
<ul class="itemize mark-bullet">
<li>The version of Octave. You can get this by noting the version number
that is printed when Octave starts, or running it with the ‘<samp class="samp">-v</samp>’
option.
</li><li>A complete input file that will reproduce the bug.
<p>A single statement may not be enough of an example—the bug might
depend on other details that are missing from the single statement where
the error finally occurs.
</p>
</li><li>The command arguments you gave Octave to execute that example
and observe the bug. To guarantee you won’t omit something important,
list all the options.
<p>If we were to try to guess the arguments, we would probably guess wrong
and then we would not encounter the bug.
</p>
</li><li>The type of machine you are using, and the operating system name and
version number.
</li><li>The command-line arguments you gave to the <code class="code">configure</code> command when
you installed the interpreter.
</li><li>A complete list of any modifications you have made to the interpreter
source.
<p>Be precise about these changes—show a context diff for them.
</p>
</li><li>Details of any other deviations from the standard procedure for installing
Octave.
</li><li><a class="index-entry-id" id="index-incorrect-output-1"></a>
<a class="index-entry-id" id="index-incorrect-results-1"></a>
<a class="index-entry-id" id="index-results_002c-incorrect-1"></a>
<a class="index-entry-id" id="index-answers_002c-incorrect-1"></a>
<a class="index-entry-id" id="index-erroneous-results-1"></a>
<a class="index-entry-id" id="index-wrong-answers-1"></a>
A description of what behavior you observe that you believe is
incorrect. For example, "The interpreter gets a fatal signal," or, "The
output produced at line 208 is incorrect."
<p>Of course, if the bug is that the interpreter gets a fatal signal, then
one can’t miss it. But if the bug is incorrect output, we might not
notice unless it is glaringly wrong.
</p>
<p>Even if the problem you experience is a fatal signal, you should still
say so explicitly. Suppose something strange is going on, such as, your
copy of the interpreter is out of sync, or you have encountered a bug
in the C library on your system. Your copy might crash and the copy
here would not. If you said to expect a crash, then when the
interpreter here fails to crash, we would know that the bug was not
happening. If you don’t say to expect a crash, then we would not know
whether the bug was happening. We would not be able to draw any
conclusion from our observations.
</p>
<p>Often the observed symptom is incorrect output when your program is run.
Unfortunately, this is not enough information unless the program is
short and simple. It is very helpful if you can include an explanation
of the expected output, and why the actual output is incorrect.
</p>
</li><li>If you wish to suggest changes to the Octave source, send them as
context diffs. If you even discuss something in the Octave source,
refer to it by context, not by line number, because the line numbers in
the development sources probably won’t match those in your sources.
</li></ul>
<p>Here are some things that are not necessary:
</p>
<ul class="itemize mark-bullet">
<li><a class="index-entry-id" id="index-bugs_002c-investigating"></a>
A description of the envelope of the bug.
<p>Often people who encounter a bug spend a lot of time investigating which
changes to the input file will make the bug go away and which changes
will not affect it. Such information is usually not necessary to enable
us to fix bugs in Octave, but if you can find a simpler example to
report <em class="emph">instead</em> of the original one, that is a convenience.
Errors in the output will be easier to spot, running under the debugger
will take less time, etc. Most Octave bugs involve just one function, so
the most straightforward way to simplify an example is to delete all the
function definitions except the one in which the bug occurs.
</p>
<p>However, simplification is not vital; if you don’t want to do
this, report the bug anyway and send the entire test case you
used.
</p>
</li><li>A patch for the bug. Patches can be helpful, but if you find a bug, you
should report it, even if you cannot send a fix for the problem.
</li></ul>
</div>
<hr>
<div class="nav-panel">
<p>
Next: <a href="Sending-Patches.html">Sending Patches for Octave</a>, Previous: <a href="Bug-Tracker.html">Where to Report Bugs</a>, Up: <a href="Reporting-Bugs.html">Reporting Bugs</a> [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Concept-Index.html" title="Index" rel="index">Index</a>]</p>
</div>
</body>
</html>
|
