|
112
|
1 @c This is the usage section for send-pr. It is called as
|
|
|
2 @c chapter (Invoking send-pr) by send-pr.texi, and also as
|
|
|
3 @c section (Submitting Problem Reports) by gnats.texi (chapter/section
|
|
|
4 @c identifiers are adjusted accordingly)
|
|
|
5
|
|
|
6 @c FIXME! This still seems jumbled...
|
|
|
7
|
|
|
8 You can invoke @code{send-pr} from a shell prompt or from within
|
|
|
9 @sc{gnu} Emacs using @w{@samp{M-x send-pr}}.
|
|
|
10
|
|
|
11 @menu
|
|
|
12 * using send-pr:: Creating new Problem Reports
|
|
|
13 * send-pr in Emacs:: Using send-pr from within Emacs
|
|
|
14 * send-pr from the shell:: Invoking send-pr from the shell
|
|
|
15 * Helpful hints::
|
|
|
16 @end menu
|
|
|
17
|
|
|
18 @node using send-pr
|
|
|
19 @section Creating new Problem Reports
|
|
|
20
|
|
|
21 @c FIXME - this is a long node
|
|
|
22 Invoking @code{send-pr} presents a PR @dfn{template} with a number of
|
|
|
23 fields already filled in. Complete the template as thoroughly as
|
|
|
24 possible to make a useful bug report. Submit only one bug with each PR.
|
|
|
25
|
|
|
26 @cindex template
|
|
|
27 A template consists of three sections:
|
|
|
28
|
|
|
29 @table @dfn
|
|
|
30 @item Comments
|
|
|
31 The top several lines of a blank template consist of a series of
|
|
|
32 comments that provide some basic instructions for completing the Problem
|
|
|
33 Report, as well as a list of valid entries for the @samp{>Category:}
|
|
|
34 field. These comments are all preceded by the string @samp{SEND-PR:}
|
|
|
35 and are erased automatically when the PR is submitted. The
|
|
|
36 instructional comments within @samp{<} and @samp{>} are also removed.
|
|
|
37 (Only these comments are removed; lines you provide that happen to have
|
|
|
38 those characters in them, such as examples of shell-level redirection,
|
|
|
39 are not affected.)
|
|
|
40
|
|
|
41 @item Mail Header
|
|
|
42 @code{send-pr} creates a standard mail header. @code{send-pr} completes
|
|
|
43 all fields except the @samp{Subject:} line with default values.
|
|
|
44 (@xref{Fields,,Problem Report format}.)
|
|
|
45
|
|
|
46 @item @sc{gnats} fields
|
|
|
47 These are the informational fields that @sc{gnats} uses to route your
|
|
|
48 Problem Report to the responsible party for further action. They should
|
|
|
49 be filled out as completely as possible. (@xref{Fields,,Problem Report
|
|
|
50 format}. Also see @ref{Helpful hints,,Helpful hints}.)
|
|
|
51 @end table
|
|
|
52
|
|
|
53 @ifset SENDPR
|
|
|
54 @noindent
|
|
|
55 For examples of a Problem Report template and complete Problem Report,
|
|
|
56 see @ref{An Example}.
|
|
|
57 @end ifset
|
|
|
58
|
|
|
59 The default template contains your preconfigured @samp{>Submitter-Id:}.
|
|
|
60 @code{send-pr} attempts to determine values for the @samp{>Originator:}
|
|
|
61 and @samp{>Organization:} fields (@pxref{Fields,,Problem Report
|
|
|
62 format}). @code{send-pr} will set the @samp{>Originator:} field to
|
|
|
63 the value of the @code{NAME} environment variable if it has been set;
|
|
|
64 similarly, @samp{>Organization:} will be set to the value of @code{ORGANIZATION}.
|
|
|
65 @code{send-pr} also attempts to find out some information
|
|
|
66 about your system and architecture, and places this information in the
|
|
|
67 @samp{>Environment:} field if it finds any.
|
|
|
68
|
|
|
69 You may submit problem reports to different Support Sites from the
|
|
|
70 default site by specifying the alternate site when you invoke
|
|
|
71 @code{send-pr}. Each @code{site} has its own list of categories for
|
|
|
72 which it accepts Problem Reports.
|
|
|
73 @c FIXME! This should go in..
|
|
|
74 @c For a list of sites to whom @code{send-pr} is configured to send
|
|
|
75 @c Problem Reports, type @w{@samp{send-pr -S}}.
|
|
|
76 @ifset SENDPR
|
|
|
77 (@xref{default site,,Setting a default @var{site}}.)
|
|
|
78 @end ifset
|
|
|
79
|
|
|
80 @code{send-pr} also provides the mail header section of the template
|
|
|
81 with default values in the @samp{To:}, @samp{From:}, and
|
|
|
82 @samp{Reply-To:} fields. The @samp{Subject:} field is empty.
|
|
|
83
|
|
|
84 The template begins with a comment section:
|
|
|
85
|
|
|
86 @cindex template comment section
|
|
|
87 @cindex comment section in the PR template
|
|
|
88 @smallexample
|
|
|
89 @group
|
|
|
90 SEND-PR: -*- send-pr -*-
|
|
|
91 SEND-PR: Lines starting with `SEND-PR' will be removed
|
|
|
92 SEND-PR: automatically as well as all comments (the text
|
|
|
93 SEND-PR: below enclosed in `<' and `>').
|
|
|
94 SEND-PR:
|
|
|
95 SEND-PR: Please consult the document `Reporting Problems
|
|
|
96 SEND-PR: Using send-pr' if you are not sure how to fill out
|
|
|
97 SEND-PR: a problem report.
|
|
|
98 SEND-PR:
|
|
|
99 SEND-PR: Choose from the following categories:
|
|
|
100 @end group
|
|
|
101 @end smallexample
|
|
|
102
|
|
|
103 @noindent
|
|
|
104 and also contains a list of valid @code{>Category:} values for the
|
|
|
105 Support Site to whom you are submitting this Problem Report. One (and
|
|
|
106 only one) of these values should be placed in the @code{>Category:}
|
|
|
107 field.
|
|
|
108 @ifset SENDPR
|
|
|
109 A complete sample bug report, from template to completed PR, is shown in
|
|
|
110 @ref{An Example}. For a complete list of valid categories, type
|
|
|
111 @w{@samp{send-pr -L}} at your prompt. @xref{Valid Categories,,Valid
|
|
|
112 Categories}, for a sample list of categories, .
|
|
|
113 @end ifset
|
|
|
114
|
|
|
115 @c FIXME.. this sounds awkward
|
|
|
116 The mail header is just below the comment section. Fill out the
|
|
|
117 @samp{Subject:} field, if it is not already completed using the value of
|
|
|
118 @samp{>Synopsis:}. The other mail header fields contain default values.
|
|
|
119
|
|
|
120 @cindex mail header section
|
|
|
121 @smallexample
|
|
|
122 @group
|
|
|
123 To: @var{support-site}
|
|
|
124 Subject: @emph{complete this field}
|
|
|
125 From: @var{your-login}@@@var{your-site}
|
|
|
126 Reply-To: @var{your-login}@@@var{your-site}
|
|
|
127 X-send-pr-version: send-pr @value{VERSION}
|
|
|
128 @end group
|
|
|
129 @end smallexample
|
|
|
130
|
|
|
131 @noindent
|
|
|
132 where @var{support-site} is an alias for the Support Site you wish to
|
|
|
133 submit this PR to.
|
|
|
134
|
|
|
135 The rest of the template contains @sc{gnats} fields. Each field is
|
|
|
136 either automatically completed with valid information (such as your
|
|
|
137 @samp{>Submitter-Id:}) or contains a one-line instruction specifying the
|
|
|
138 information that field requires in order to be correct. For example,
|
|
|
139 the @samp{>Confidential:} field expects a value of @samp{yes} or
|
|
|
140 @samp{no}, and the answer must fit on one line; similarly, the
|
|
|
141 @samp{>Synopsis:} field expects a short synopsis of the problem, which
|
|
|
142 must also fit on one line. Fill out the fields as completely as
|
|
|
143 possible. @xref{Helpful hints,,Helpful hints}, for suggestions as to
|
|
|
144 what kinds of information to include.
|
|
|
145
|
|
|
146 In this example, words in @emph{italics} are filled in with
|
|
|
147 pre-configured information:
|
|
|
148
|
|
|
149 @cindex @code{send-pr} fields
|
|
|
150 @smallexample
|
|
|
151 @group
|
|
|
152 >Submitter-Id: @emph{your submitter-id}
|
|
|
153 >Originator: @emph{your name here}
|
|
|
154 >Organization:
|
|
|
155 @emph{your organization}
|
|
|
156 >Confidential:<[ yes | no ] (one line)>
|
|
|
157 >Synopsis: <synopsis of the problem (one line)>
|
|
|
158 >Severity: <[non-critical | serious | critical](one line)>
|
|
|
159 >Priority: <[ low | medium | high ] (one line)>
|
|
|
160 >Category: <name of the product (one line)>
|
|
|
161 >Class: <[sw-bug | doc-bug | change-request | support]>
|
|
|
162 >Release: <release number (one line)>
|
|
|
163 >Environment:
|
|
|
164 <machine, os, target, libraries (multiple lines)>
|
|
|
165
|
|
|
166 >Description:
|
|
|
167 <precise description of the problem (multiple lines)>
|
|
|
168 >How-To-Repeat:
|
|
|
169 <code/input/activities to reproduce (multiple lines)>
|
|
|
170 >Fix:
|
|
|
171 <how to correct or work around the problem, if known
|
|
|
172 (multiple lines)>
|
|
|
173 @end group
|
|
|
174 @end smallexample
|
|
|
175
|
|
|
176 @cindex @code{Submitter-Id} field
|
|
|
177 @cindex @code{>Submitter-Id:}
|
|
|
178 When you finish editing the Problem Report, @code{send-pr} mails it to
|
|
|
179 the address named in the @samp{To:} field in the mail header.
|
|
|
180 @code{send-pr} checks that the complete form contains a valid
|
|
|
181 @samp{>Category:}.
|
|
|
182
|
|
|
183 @ifset SENDPR
|
|
|
184 Your copy of @code{send-pr} should have already been customized on
|
|
|
185 installation to reflect your @samp{>Submitter-Id:}. (@xref{Installing
|
|
|
186 send-pr, , Installing @code{send-pr} on your system}.) If you don't
|
|
|
187 know your @samp{>Submitter-Id:}, you can request it using
|
|
|
188 @w{@samp{send-pr --request-id}}. If your organization is not affiliated
|
|
|
189 with the site you send Problem Reports to, a good generic
|
|
|
190 @samp{>Submitter-Id:} to use is @samp{net}.
|
|
|
191 @end ifset
|
|
|
192
|
|
|
193 @cindex bad Problem Reports
|
|
|
194 @cindex errors
|
|
|
195 @cindex invalid Problem Reports
|
|
|
196 If your PR has an invalid value in one of the @sc{Enumerated} fields
|
|
|
197 (@pxref{Fields,,Problem Report format}), @code{send-pr} places the PR in
|
|
|
198 a temporary file named @samp{/tmp/pbad@var{nnnn}} on your machine.
|
|
|
199 @var{nnnn} is the process identification number given to your current
|
|
|
200 @code{send-pr} session. If you are running @code{send-pr} from the
|
|
|
201 shell, you are prompted as to whether or not you wish to try editing the
|
|
|
202 same Problem Report again. If you are running @code{send-pr} from
|
|
|
203 Emacs, the Problem Report is placed in the buffer
|
|
|
204 @w{@samp{*send-pr-error*}}; you can edit this file and then submit it
|
|
|
205 with
|
|
|
206
|
|
|
207 @smallexample
|
|
|
208 M-x gnats-submit-pr
|
|
|
209 @end smallexample
|
|
|
210
|
|
|
211 @cindex subsequent mail
|
|
|
212 @cindex other mail
|
|
|
213 @cindex appending PRs
|
|
|
214 @cindex saving related mail
|
|
|
215 @cindex related mail
|
|
|
216 Any further mail concerning this Problem Report should be carbon-copied
|
|
|
217 to the @sc{gnats} mailing address as well, with the category and
|
|
|
218 identification number in the @samp{Subject:} line of the message.
|
|
|
219
|
|
|
220 @smallexample
|
|
|
221 Subject: Re: PR @var{category}/@var{gnats-id}: @var{original message subject}
|
|
|
222 @end smallexample
|
|
|
223
|
|
|
224 @noindent
|
|
|
225 Messages which arrive with @samp{Subject:} lines of this form are
|
|
|
226 automatically appended to the Problem Report in the @samp{>Audit-Trail:}
|
|
|
227 field in the order received.
|
|
|
228
|
|
|
229 @c ---------------------------------------------------------------
|
|
|
230 @node send-pr in Emacs
|
|
|
231 @section Using @code{send-pr} from within Emacs
|
|
|
232 @cindex using @code{send-pr} from within Emacs
|
|
|
233 @cindex @code{send-pr} within Emacs
|
|
|
234 @cindex invoking @code{send-pr} from Emacs
|
|
|
235 @cindex interactive interface
|
|
|
236
|
|
|
237 You can use an interactive @code{send-pr} interface from within @sc{gnu}
|
|
|
238 Emacs to fill out your Problem Report. We recommend that you
|
|
|
239 familiarize yourself with Emacs before using this feature
|
|
|
240 (@pxref{Introduction,,Introduction,emacs,GNU Emacs}).
|
|
|
241
|
|
|
242 Call @code{send-pr} with @w{@samp{M-x send-pr}}.@footnote{If typing
|
|
|
243 @w{@samp{M-x send-pr}} doesn't work, see your system administrator for
|
|
|
244 help loading @code{send-pr} into Emacs.} @code{send-pr} responds with a
|
|
|
245 Problem Report template preconfigured for the Support Site from which
|
|
|
246 you received @code{send-pr}. (If you use @code{send-pr} locally, the
|
|
|
247 default Support Site is probably your local site.)
|
|
|
248
|
|
|
249 You may also submit problem reports to different Support Sites from the
|
|
|
250 default site. To use this feature, invoke @code{send-pr} with
|
|
|
251
|
|
|
252 @smallexample
|
|
|
253 C-u M-x send-pr
|
|
|
254 @end smallexample
|
|
|
255
|
|
|
256 @code{send-pr} prompts you for the name of a @var{site}. @var{site} is
|
|
|
257 an alias on your local machine which points to an alternate Support
|
|
|
258 Site.
|
|
|
259
|
|
|
260 @cindex Emacs
|
|
|
261 @code{send-pr} displays the template and prompts you in the minibuffer
|
|
|
262 with the line:
|
|
|
263 @smallexample
|
|
|
264 >Category: other
|
|
|
265 @end smallexample
|
|
|
266
|
|
|
267 @noindent
|
|
|
268 Delete the default value @samp{other} @emph{in the minibuffer} and
|
|
|
269 replace it with the keyword corresponding to your problem (the list of
|
|
|
270 valid categories is in the topmost section of the PR template). For
|
|
|
271 example, if the problem you wish to report has to do with the @sc{gnu} C
|
|
|
272 compiler, and your support organization accepts bugs submitted for this
|
|
|
273 program under the category @samp{gcc}, delete @samp{other} and then type
|
|
|
274 @w{@samp{gcc[@key{RET}]}}. @code{send-pr} replaces the line
|
|
|
275
|
|
|
276 @smallexample
|
|
|
277 >Category: <name of the product (one line)>
|
|
|
278 @end smallexample
|
|
|
279
|
|
|
280 @noindent
|
|
|
281 in the template with
|
|
|
282
|
|
|
283 @smallexample
|
|
|
284 >Category: gcc
|
|
|
285 @end smallexample
|
|
|
286
|
|
|
287 @noindent
|
|
|
288 and moves on to another field.
|
|
|
289
|
|
|
290 @cindex completion in Emacs
|
|
|
291 @cindex name completion in Emacs
|
|
|
292 @w{@code{send-pr}} provides name completion in the minibuffer. For
|
|
|
293 instance, you can also type @w{@samp{gc[@key{TAB}]}}, and @code{send-pr}
|
|
|
294 attempts to complete the entry for you. Typing @w{@samp{g[@key{TAB}]}}
|
|
|
295 may not have the same effect if several possible entries begin with
|
|
|
296 @samp{g}. In that case @code{send-pr} cannot complete the entry because
|
|
|
297 it cannot determine whether you mean @samp{gcc} or, for example,
|
|
|
298 @samp{gdb}, if both of those are possible categories.
|
|
|
299 @w{@code{send-pr}} continues to prompt you for a valid entry until you
|
|
|
300 enter one.
|
|
|
301
|
|
|
302 @w{@code{send-pr}} prompts you interactively to enter each field for
|
|
|
303 which there is a range of specific choices. If you attempt to enter a
|
|
|
304 value which is not in the range of acceptable entries, @code{send-pr}
|
|
|
305 responds with @w{@samp{[No match]}} and allows you to change the entry
|
|
|
306 until it contains an acceptable value. This avoids unusable information
|
|
|
307 (at least in these fields) and also avoids typographical errors which
|
|
|
308 could cause problems later.
|
|
|
309
|
|
|
310 @code{send-pr} prompts you for the following fields:
|
|
|
311
|
|
|
312 @c FIXME - should these go before the discussion on completion?
|
|
|
313 @example
|
|
|
314 @group
|
|
|
315 >Category:
|
|
|
316 >Confidential: (@emph{default}: no)
|
|
|
317 >Severity: (@emph{default}: serious)
|
|
|
318 >Priority: (@emph{default}: medium)
|
|
|
319 >Class: (@emph{default}: sw-bug)
|
|
|
320 >Release:
|
|
|
321 >Synopsis: (@emph{this value is copied to @code{Subject:}})
|
|
|
322 @end group
|
|
|
323 @end example
|
|
|
324
|
|
|
325 @noindent
|
|
|
326 After you complete these fields, @w{@code{send-pr}} places the cursor in
|
|
|
327 the @samp{>Description:} field and displays the message
|
|
|
328
|
|
|
329 @smallexample
|
|
|
330 To send the problem report use: C-c C-c
|
|
|
331 @end smallexample
|
|
|
332
|
|
|
333 @noindent
|
|
|
334 in the minibuffer. At this point, edit the file in the main buffer to
|
|
|
335 reflect your specific problem, putting relevant information in the
|
|
|
336 proper fields.
|
|
|
337 @ifset SENDPR
|
|
|
338 @xref{An Example}, for a sample Problem Report.
|
|
|
339 @end ifset
|
|
|
340
|
|
|
341 @w{@samp{send-pr}} provides a few key bindings to make moving
|
|
|
342 around in a template buffer more simple:
|
|
|
343
|
|
|
344 @table @code
|
|
|
345 @item C-c C-f
|
|
|
346 @itemx M-x change-field
|
|
|
347 Changes the field under the cursor. @code{edit-pr} prompts you for a
|
|
|
348 new value.
|
|
|
349
|
|
|
350 @item M-C-b
|
|
|
351 @itemx M-x gnats-backward-field
|
|
|
352 Moves the cursor to the beginning of the value of the current field.
|
|
|
353
|
|
|
354 @item M-C-f
|
|
|
355 @itemx M-x gnats-forward-field
|
|
|
356 Moves the cursor to the end of the value of the current field.
|
|
|
357
|
|
|
358 @item M-p
|
|
|
359 @itemx M-x gnats-previous-field
|
|
|
360 Moves the cursor back one field to the beginning of the value of the
|
|
|
361 previous field.
|
|
|
362
|
|
|
363 @item M-n
|
|
|
364 @itemx M-x gnats-next-field
|
|
|
365 Moves the cursor forward one field to the beginning of the value of the
|
|
|
366 next field.
|
|
|
367 @end table
|
|
|
368
|
|
|
369 @code{send-pr} takes over again when you type @samp{C-c C-c} to send the
|
|
|
370 message. @code{send-pr} reports any errors in a separate buffer, which
|
|
|
371 remains in existence until you send the PR properly (or, of course,
|
|
|
372 until you explicitly kill the buffer).
|
|
|
373
|
|
|
374 For detailed instructions on using Emacs, see
|
|
|
375 @ref{Introduction,,,emacs,GNU Emacs}.
|
|
|
376
|
|
|
377 @node send-pr from the shell
|
|
|
378 @section Invoking @code{send-pr} from the shell
|
|
|
379 @cindex command line options
|
|
|
380 @cindex invoking @code{send-pr} from the shell
|
|
|
381 @cindex shell invocation
|
|
|
382
|
|
|
383 @c FIXME! Add [ -S ] right after [ -L ]...
|
|
|
384 @smallexample
|
|
|
385 send-pr [ @var{site} ]
|
|
|
386 [ -f @var{problem-report} | --file @var{problem-report} ]
|
|
|
387 [ -t @var{mail-address} | --to @var{mail-address} ]
|
|
|
388 [ --request-id ]
|
|
|
389 [ -L | --list ] [ -P | --print ]
|
|
|
390 [ -V | --version] [ -h | --help ]
|
|
|
391 @end smallexample
|
|
|
392
|
|
|
393 @var{site} is an alias on your local machine which points to an address
|
|
|
394 used by a Support Site. If this argument is not present, the default
|
|
|
395 @var{site} is usually the site which you received @code{send-pr} from,
|
|
|
396 or your local site if you use @sc{gnats} locally.
|
|
|
397 @ifset SENDPR
|
|
|
398 (@xref{default site,,Setting a default @var{site}}.)
|
|
|
399 @end ifset
|
|
|
400
|
|
|
401 Invoking @code{send-pr} with no options calls the editor named in your
|
|
|
402 environment variable @code{EDITOR} on a default PR template. If the
|
|
|
403 environment variable @code{PR_FORM} is set, its value is used as a file
|
|
|
404 name which contains a valid template. If @code{PR_FORM} points to a
|
|
|
405 missing or unreadable file, or if the file is empty, @code{send-pr}
|
|
|
406 generates an error message and opens the editor on a default template.
|
|
|
407
|
|
|
408 @table @code
|
|
|
409 @item -f @var{problem-report}
|
|
|
410 @itemx --file @var{problem-report}
|
|
|
411 Specifies a file, @var{problem-report}, where a completed Problem Report
|
|
|
412 already exists. @code{send-pr} sends the contents of the file without
|
|
|
413 invoking an editor. If @var{problem-report} is @samp{-},
|
|
|
414 @w{@code{send-pr}} reads from standard input.
|
|
|
415
|
|
|
416 @item -t @var{mail-address}
|
|
|
417 @itemx --to @var{mail-address}
|
|
|
418 Sends the PR to @var{mail-address}. The default is preset when
|
|
|
419 @code{send-pr} is configured. @emph{This option is not recommended};
|
|
|
420 instead, use the argument @var{site} on the command line.
|
|
|
421
|
|
|
422 @item -c @var{mail-address}
|
|
|
423 @itemx --cc @var{mail-address}
|
|
|
424 Places @var{mail-address} in the @code{Cc:} header field of the message
|
|
|
425 to be sent.
|
|
|
426
|
|
|
427 @item --request-id
|
|
|
428 Sends a request for a @code{>Submitter-Id:} to the Support Site.
|
|
|
429
|
|
|
430 @cindex listing valid categories
|
|
|
431 @item -L
|
|
|
432 @itemx --list
|
|
|
433 Prints the list of valid @code{>Category:} values on standard output.
|
|
|
434 No mail is sent.
|
|
|
435
|
|
|
436 @item -s @var{severity}
|
|
|
437 @itemx --severity @var{severity}
|
|
|
438 @cindex @code{send-pr} fields
|
|
|
439 Sets the initial value of the @code{>Severity:} field to @var{severity}.
|
|
|
440
|
|
|
441 @ignore
|
|
|
442 @item -S
|
|
|
443 @itemx --sites
|
|
|
444 Displays a list of valid @var{site} values on standard output. No mail
|
|
|
445 is sent.
|
|
|
446 @end ignore
|
|
|
447
|
|
|
448 @item -P
|
|
|
449 @itemx --print
|
|
|
450 Displays the PR template. If the variable @code{PR_FORM} is set in your
|
|
|
451 environment, the file it specifies is printed. If @code{PR_FORM} is not
|
|
|
452 set, @code{send-pr} prints the standard blank form. If the file
|
|
|
453 specified by @code{PR_FORM} doesn't exist, @code{send-pr} displays an
|
|
|
454 error message. No mail is sent.
|
|
|
455
|
|
|
456 @item -V
|
|
|
457 @itemx --version
|
|
|
458 Displays the @code{send-pr} version number and a usage summary. No mail
|
|
|
459 is sent.
|
|
|
460
|
|
|
461 @item -h
|
|
|
462 @itemx --help
|
|
|
463 Displays a usage summary for @code{send-pr}. No mail is sent.
|
|
|
464 @end table
|
|
|
465
|
|
|
466 @node Helpful hints
|
|
|
467 @section Helpful hints
|
|
|
468 @cindex helpful hints
|
|
|
469 @cindex Using and Porting @sc{gnu} CC
|
|
|
470 @cindex effective problem reporting
|
|
|
471 @cindex kinds of helpful information
|
|
|
472 @cindex information to submit
|
|
|
473 @cindex Report all the facts!
|
|
|
474
|
|
|
475 There is no orthodox standard for submitting effective bug reports,
|
|
|
476 though you might do well to consult the section on submitting bugs for
|
|
|
477
|
|
|
478 @sc{gnu} @code{gcc} in @ref{Bugs, , Reporting Bugs, gcc, Using and
|
|
|
479 Porting GNU CC}, by Richard Stallman. This section contains
|
|
|
480 instructions on what kinds of information to include and what kinds of
|
|
|
481 mistakes to avoid.
|
|
|
482
|
|
|
483 In general, common sense (assuming such an animal exists) dictates the
|
|
|
484 kind of information that would be most helpful in tracking down and
|
|
|
485 resolving problems in software.
|
|
|
486 @itemize @bullet
|
|
|
487 @item
|
|
|
488 Include anything @emph{you} would want to know if you were looking at
|
|
|
489 the report from the other end. There's no need to include every minute
|
|
|
490 detail about your environment, although anything that might be different
|
|
|
491 from someone else's environment should be included (your path, for
|
|
|
492 instance).
|
|
|
493
|
|
|
494 @item
|
|
|
495 Narratives are often useful, given a certain degree of restraint. If a
|
|
|
496 person responsible for a bug can see that A was executed, and then B and
|
|
|
497 then C, knowing that sequence of events might trigger the realization of
|
|
|
498 an intermediate step that was missing, or an extra step that might have
|
|
|
499 changed the environment enough to cause a visible problem. Again,
|
|
|
500 restraint is always in order (``I set the build running, went to get a
|
|
|
501 cup of coffee (Columbian, cream but no sugar), talked to Sheila on the
|
|
|
502 phone, and then THIS happened@dots{}'') but be sure to include anything
|
|
|
503 relevant.
|
|
|
504
|
|
|
505 @item
|
|
|
506 Richard Stallman writes, ``The fundamental principle of reporting bugs
|
|
|
507 usefully is this: @strong{report all the facts}. If you are not sure
|
|
|
508 whether to state a fact or leave it out, state it!'' This holds true
|
|
|
509 across all problem reporting systems, for computer software or social
|
|
|
510 injustice or motorcycle maintenance. It is especially important in the
|
|
|
511 software field due to the major differences seemingly insignificant
|
|
|
512 changes can make (a changed variable, a missing semicolon, etc.).
|
|
|
513
|
|
|
514 @item
|
|
|
515 Submit only @emph{one} problem with each Problem Report. If you have
|
|
|
516 multiple problems, use multiple PRs. This aids in tracking each problem
|
|
|
517 and also in analyzing the problems associated with a given program.
|
|
|
518
|
|
|
519 @item
|
|
|
520 It never hurts to do a little research to find out if the bug you've
|
|
|
521 found has already been reported. Most software releases contain lists
|
|
|
522 of known bugs in the Release Notes which come with the software; see
|
|
|
523 your system administrator if you don't have a copy of these.
|
|
|
524
|
|
|
525 @item
|
|
|
526 The more closely a PR adheres to the standard format, the less
|
|
|
527 interaction is required by a database administrator to route the
|
|
|
528 information to the proper place. Keep in mind that anything that
|
|
|
529 requires human interaction also requires time that might be better spent
|
|
|
530 in actually fixing the problem. It is therefore in everyone's best
|
|
|
531 interest that the information contained in a PR be as correct as
|
|
|
532 possible (in both format and content) at the time of submission.
|
|
|
533 @end itemize
|
