3 @c This is the usage section for send-pr. It is called as
4 @c chapter (Invoking send-pr) by send-pr.texi, and also as
5 @c section (Submitting Problem Reports) by gnats.texi (chapter/section
6 @c identifiers are adjusted accordingly)
8 @c FIXME! This still seems jumbled...
10 You can invoke @code{send-pr} from a shell prompt, or from within
11 @sc{gnu} Emacs using @w{@samp{M-x send-pr}}.
14 * using send-pr:: Creating new Problem Reports
15 * send-pr in Emacs:: Using send-pr from within Emacs
16 * send-pr from the shell:: Invoking send-pr from the shell
17 * Submitting via e-mail:: Submitting a Problem Report via direct e-mail
22 @section Creating new Problem Reports
24 @c FIXME - this is a long node
25 Invoking @code{send-pr} presents a PR @dfn{template} with a number of
26 fields already filled in. Complete the template as thoroughly as
27 possible to make a useful bug report. Submit only one bug with each PR.
30 A template consists of three sections:
34 The top several lines of a blank template consist of a series of
35 comments that provide some basic instructions for completing the Problem
36 Report, as well as a list of valid entries for the @samp{>Category:}
37 field. These comments are all preceded by the string @samp{SEND-PR:}
38 and are erased automatically when the PR is submitted. The
39 instructional comments within @samp{<} and @samp{>} are also removed.
40 (Only these comments are removed; lines you provide that happen to have
41 those characters in them, such as examples of shell-level redirection,
45 @code{send-pr} creates a standard mail header. @code{send-pr} completes
46 all fields except the @samp{Subject:} line with default values.
47 (@xref{Fields,,Problem Report format}.)
49 @item @sc{gnats} fields
50 These are the informational fields that @sc{gnats} uses to route your
51 Problem Report to the responsible party for further action. They should
52 be filled out as completely as possible. (@xref{Fields,,Problem Report
53 format}. Also see @ref{Helpful hints,,Helpful hints}.)
58 For examples of a Problem Report template and complete Problem Report,
62 The default template contains your preconfigured @samp{>Submitter-Id:}.
63 @code{send-pr} attempts to determine values for the @samp{>Originator:}
64 and @samp{>Organization:} fields (@pxref{Fields,,Problem Report
65 format}). @code{send-pr} will set the @samp{>Originator:} field to
66 the value of the @code{NAME} environment variable if it has been set;
67 similarly, @samp{>Organization:} will be set to the value of @code{ORGANIZATION}.
68 @code{send-pr} also attempts to find out some information
69 about your system and architecture, and places this information in the
70 @samp{>Environment:} field if it finds any.
72 You may submit problem reports to different Support Sites from the
73 default site by specifying the alternate site when you invoke
74 @code{send-pr}. @xref{send-pr from the shell}.
75 Each @code{site} has its own list of categories for
76 which it accepts Problem Reports.
77 @c FIXME! This should go in..
78 @c For a list of sites to whom @code{send-pr} is configured to send
79 @c Problem Reports, type @w{@samp{send-pr -S}}.
81 (@xref{default site,,Setting a default @var{site}}.)
84 @code{send-pr} also provides the mail header section of the template
85 with default values in the @samp{To:}, @samp{From:}, and
86 @samp{Reply-To:} fields. The @samp{Subject:} field is empty.
88 The template begins with a comment section:
90 @cindex template comment section
91 @cindex comment section in the PR template
94 SEND-PR: -*- send-pr -*-
95 SEND-PR: Lines starting with `SEND-PR' will be removed
96 SEND-PR: automatically as well as all comments (the text
97 SEND-PR: below enclosed in `<' and `>').
99 SEND-PR: Please consult the document `Reporting Problems
100 SEND-PR: Using send-pr' if you are not sure how to fill out
101 SEND-PR: a problem report.
103 SEND-PR: Choose from the following categories:
108 and also contains a list of valid @code{>Category:} values for the
109 Support Site to whom you are submitting this Problem Report. One (and
110 only one) of these values should be placed in the @code{>Category:}
113 A complete sample bug report, from template to completed PR, is shown in
114 @ref{An Example}. For a complete list of valid categories, type
115 @w{@samp{send-pr -L}} at your prompt. @xref{Valid Categories,,Valid
116 Categories}, for a sample list of categories, .
119 @c FIXME.. this sounds awkward
120 The mail header is just below the comment section. Fill out the
121 @samp{Subject:} field, if it is not already completed using the value of
122 @samp{>Synopsis:}. The other mail header fields contain default values.
124 @cindex mail header section
127 To: @var{support-site}
128 Subject: @emph{complete this field}
129 From: @var{your-login}@@@var{your-site}
130 Reply-To: @var{your-login}@@@var{your-site}
131 X-send-pr-version: send-pr @value{VERSION}
136 where @var{support-site} is an alias on your local machine for the
137 Support Site you wish to submit this PR to.
139 The rest of the template contains @sc{gnats} fields. Each field is
140 either automatically completed with valid information (such as your
141 @samp{>Submitter-Id:}) or contains a one-line instruction specifying the
142 information that field requires in order to be correct. For example,
143 the @samp{>Confidential:} field expects a value of @samp{yes} or
144 @samp{no}, and the answer must fit on one line; similarly, the
145 @samp{>Synopsis:} field expects a short synopsis of the problem, which
146 must also fit on one line. Fill out the fields as completely as
147 possible. @xref{Helpful hints,,Helpful hints}, for suggestions as to
148 what kinds of information to include.
150 In this example, words in @emph{italics} are filled in with
151 pre-configured information:
153 @cindex @code{send-pr} fields
156 >Submitter-Id: @emph{your submitter-id}
157 >Originator: @emph{your name here}
159 @emph{your organization}
160 >Confidential:<[ yes | no ] (one line)>
161 >Synopsis: <synopsis of the problem (one line)>
162 >Severity: <[non-critical | serious | critical](one line)>
163 >Priority: <[ low | medium | high ] (one line)>
164 >Category: <name of the product (one line)>
165 >Class: <[sw-bug | doc-bug | change-request | support]>
166 >Release: <release number (one line)>
168 <machine, os, target, libraries (multiple lines)>
171 <precise description of the problem (multiple lines)>
173 <code/input/activities to reproduce (multiple lines)>
175 <how to correct or work around the problem, if known
180 @cindex @code{Submitter-Id} field
181 @cindex @code{>Submitter-Id:}
182 When you finish editing the Problem Report, @code{send-pr} mails it to
183 the address named in the @samp{To:} field in the mail header.
184 @code{send-pr} checks that the complete form contains a valid
188 Your copy of @code{send-pr} should have already been customized on
189 installation to reflect your @samp{>Submitter-Id:}. (@xref{Installing
190 send-pr, , Installing @code{send-pr} on your system}.) If you don't
191 know your @samp{>Submitter-Id:}, you can request it using
192 @w{@samp{send-pr --request-id}}. If your organization is not affiliated
193 with the site you send Problem Reports to, a good generic
194 @samp{>Submitter-Id:} to use is @samp{net}. @emph{NOTE:} If you are using
195 send-pr to send problem reports to the FreeBSD Project, this version of
196 send-pr already has a customer ID in it and you do not need to request a
200 @cindex bad Problem Reports
202 @cindex invalid Problem Reports
203 If your PR has an invalid value in one of the @sc{Enumerated} fields
204 (@pxref{Fields,,Problem Report format}), @code{send-pr} places the PR in
205 a temporary file named @samp{/tmp/pbad@var{nnnn}} on your machine.
206 @var{nnnn} is the process identification number given to your current
207 @code{send-pr} session. If you are running @code{send-pr} from the
208 shell, you are prompted as to whether or not you wish to try editing the
209 same Problem Report again. If you are running @code{send-pr} from
210 Emacs, the Problem Report is placed in the buffer
211 @w{@samp{*send-pr-error*}}; you can edit this file and then submit it
218 @cindex subsequent mail
220 @cindex appending PRs
221 @cindex saving related mail
223 Any further mail concerning this Problem Report should be carbon-copied
224 to the @sc{gnats} mailing address as well, with the category and
225 identification number in the @samp{Subject:} line of the message.
228 Subject: Re: PR @var{category}/@var{gnats-id}: @var{original message subject}
232 Messages which arrive with @samp{Subject:} lines of this form are
233 automatically appended to the Problem Report in the @samp{>Audit-Trail:}
234 field in the order received.
236 @c ---------------------------------------------------------------
237 @node send-pr in Emacs
238 @section Using @code{send-pr} from within Emacs
239 @cindex using @code{send-pr} from within Emacs
240 @cindex @code{send-pr} within Emacs
241 @cindex invoking @code{send-pr} from Emacs
242 @cindex interactive interface
244 You can use an interactive @code{send-pr} interface from within @sc{gnu}
245 Emacs to fill out your Problem Report. We recommend that you
246 familiarize yourself with Emacs before using this feature
247 (@pxref{Introduction,,Introduction,emacs,GNU Emacs}).
249 Call @code{send-pr} with @w{@samp{M-x send-pr}}.@footnote{If typing
250 @w{@samp{M-x send-pr}} doesn't work, see your system administrator for
251 help loading @code{send-pr} into Emacs.} @code{send-pr} responds with a
252 Problem Report template preconfigured for the Support Site from which
253 you received @code{send-pr}. (If you use @code{send-pr} locally, the
254 default Support Site is probably your local site.)
256 You may also submit problem reports to different Support Sites from the
257 default site. To use this feature, invoke @code{send-pr} with
263 @code{send-pr} prompts you for the name of a @var{site}. @var{site} is
264 an alias on your local machine which points to an alternate Support
268 @code{send-pr} displays the template and prompts you in the minibuffer
275 Delete the default value @samp{other} @emph{in the minibuffer} and
276 replace it with the keyword corresponding to your problem (the list of
277 valid categories is in the topmost section of the PR template). For
278 example, if the problem you wish to report has to do with the @sc{gnu} C
279 compiler, and your support organization accepts bugs submitted for this
280 program under the category @samp{gcc}, delete @samp{other} and then type
281 @w{@samp{gcc[@key{RET}]}}. @code{send-pr} replaces the line
284 >Category: <name of the product (one line)>
295 and moves on to another field.
297 @cindex completion in Emacs
298 @cindex name completion in Emacs
299 @w{@code{send-pr}} provides name completion in the minibuffer. For
300 instance, you can also type @w{@samp{gc[@key{TAB}]}}, and @code{send-pr}
301 attempts to complete the entry for you. Typing @w{@samp{g[@key{TAB}]}}
302 may not have the same effect if several possible entries begin with
303 @samp{g}. In that case @code{send-pr} cannot complete the entry because
304 it cannot determine whether you mean @samp{gcc} or, for example,
305 @samp{gdb}, if both of those are possible categories.
306 @w{@code{send-pr}} continues to prompt you for a valid entry until you
309 @w{@code{send-pr}} prompts you interactively to enter each field for
310 which there is a range of specific choices. If you attempt to enter a
311 value which is not in the range of acceptable entries, @code{send-pr}
312 responds with @w{@samp{[No match]}} and allows you to change the entry
313 until it contains an acceptable value. This avoids unusable information
314 (at least in these fields) and also avoids typographical errors which
315 could cause problems later.
317 @code{send-pr} prompts you for the following fields:
319 @c FIXME - should these go before the discussion on completion?
323 >Confidential: (@emph{default}: no)
324 >Severity: (@emph{default}: serious)
325 >Priority: (@emph{default}: medium)
326 >Class: (@emph{default}: sw-bug)
328 >Synopsis: (@emph{this value is copied to @code{Subject:}})
333 After you complete these fields, @w{@code{send-pr}} places the cursor in
334 the @samp{>Description:} field and displays the message
337 To send the problem report use: C-c C-c
341 in the minibuffer. At this point, edit the file in the main buffer to
342 reflect your specific problem, putting relevant information in the
345 @xref{An Example}, for a sample Problem Report.
348 @w{@samp{send-pr}} provides a few key bindings to make moving
349 around in a template buffer more simple:
353 @itemx M-x change-field
354 Changes the field under the cursor. @code{edit-pr} prompts you for a
358 @itemx M-x gnats-backward-field
359 Moves the cursor to the beginning of the value of the current field.
362 @itemx M-x gnats-forward-field
363 Moves the cursor to the end of the value of the current field.
366 @itemx M-x gnats-previous-field
367 Moves the cursor back one field to the beginning of the value of the
371 @itemx M-x gnats-next-field
372 Moves the cursor forward one field to the beginning of the value of the
376 @code{send-pr} takes over again when you type @samp{C-c C-c} to send the
377 message. @code{send-pr} reports any errors in a separate buffer, which
378 remains in existence until you send the PR properly (or, of course,
379 until you explicitly kill the buffer).
381 For detailed instructions on using Emacs, see
382 @ref{Introduction,,,emacs,GNU Emacs}.
384 @node send-pr from the shell
385 @section Invoking @code{send-pr} from the shell
386 @cindex command line options
387 @cindex invoking @code{send-pr} from the shell
388 @cindex shell invocation
390 @c FIXME! Add [ -S ] right after [ -L ]...
392 send-pr [ @var{site} ]
393 [ -f @var{problem-report} | --file @var{problem-report} ]
394 [ -t @var{mail-address} | --to @var{mail-address} ]
396 [ -L | --list ] [ -P | --print ]
397 [ -V | --version] [ -h | --help ]
400 @var{site} is an alias on your local machine which points to an address
401 used by a Support Site. If this argument is not present, the default
402 @var{site} is usually the site which you received @code{send-pr} from,
403 or your local site if you use @sc{gnats} locally.
405 (@xref{default site,,Setting a default @var{site}}.)
408 Invoking @code{send-pr} with no options calls the editor named in your
409 environment variable @code{EDITOR} on a default PR template. If the
410 environment variable @code{PR_FORM} is set, its value is used as a file
411 name which contains a valid template. If @code{PR_FORM} points to a
412 missing or unreadable file, or if the file is empty, @code{send-pr}
413 generates an error message and opens the editor on a default template.
416 @item -f @var{problem-report}
417 @itemx --file @var{problem-report}
418 Specifies a file, @var{problem-report}, where a completed Problem Report
419 already exists. @code{send-pr} sends the contents of the file without
420 invoking an editor. If @var{problem-report} is @samp{-},
421 @w{@code{send-pr}} reads from standard input.
423 @item -t @var{mail-address}
424 @itemx --to @var{mail-address}
425 Sends the PR to @var{mail-address}. The default is preset when
426 @code{send-pr} is configured. @emph{This option is not recommended};
427 instead, use the argument @var{site} on the command line.
429 @item -c @var{mail-address}
430 @itemx --cc @var{mail-address}
431 Places @var{mail-address} in the @code{Cc:} header field of the message
435 Sends a request for a @code{>Submitter-Id:} to the Support Site.
437 @cindex listing valid categories
440 Prints the list of valid @code{>Category:} values on standard output.
443 @item -s @var{severity}
444 @itemx --severity @var{severity}
445 @cindex @code{send-pr} fields
446 Sets the initial value of the @code{>Severity:} field to @var{severity}.
451 Displays a list of valid @var{site} values on standard output. No mail
457 Displays the PR template. If the variable @code{PR_FORM} is set in your
458 environment, the file it specifies is printed. If @code{PR_FORM} is not
459 set, @code{send-pr} prints the standard blank form. If the file
460 specified by @code{PR_FORM} doesn't exist, @code{send-pr} displays an
461 error message. No mail is sent.
465 Displays the @code{send-pr} version number and a usage summary. No mail
470 Displays a usage summary for @code{send-pr}. No mail is sent.
473 @c -------------------------------------------------------------------------
474 @node Submitting via e-mail
475 @section Submitting a Problem Report via direct e-mail
476 @cindex Direct e-mail
477 @cindex Submitting a PR via e-mail
478 In addition to using @code{send-pr}, there is another way to submit a problem
479 report. You can simply send an e-mail message to the support site.
481 To do this, look at the address in the @samp{To:} field of the @code{send-pr}
482 template. When you send unformatted e-mail to this address, @sc{gnats}
483 processes the message as a new problem report, filling in as many fields from
488 The @samp{>Synopsis} field is filled in by the @samp{Subject:} header.
491 @sc{gnats} will try to derive the @samp{>Submitter} field from the address
492 in the @samp{From:} header.
495 All of the text in the body of the e-mail message is put into the
496 @samp{>Description} field. Each line of the text is indented by one space,
497 indicating that it is "quoted text" from the sender.
500 Other fields, such as category, version, severity, etc. are set to default
501 values (if the @sc{gnats} administrator has set them).
503 @c --------------------------------------------------------------------------
505 @section Helpful hints
506 @cindex helpful hints
507 @cindex Using and Porting @sc{gnu} CC
508 @cindex effective problem reporting
509 @cindex kinds of helpful information
510 @cindex information to submit
511 @cindex Report all the facts!
513 There is no orthodox standard for submitting effective bug reports,
514 though you might do well to consult the section on submitting bugs for
515 @sc{gnu} @code{gcc} in @ref{Bugs, , Reporting Bugs, gcc, Using and
516 Porting GNU CC}, by Richard Stallman. This section contains
517 instructions on what kinds of information to include and what kinds of
520 In general, common sense (assuming such an animal exists) dictates the
521 kind of information that would be most helpful in tracking down and
522 resolving problems in software.
525 Include anything @emph{you} would want to know if you were looking at
526 the report from the other end. There's no need to include every minute
527 detail about your environment, although anything that might be different
528 from someone else's environment should be included (your path, for
532 Narratives are often useful, given a certain degree of restraint. If a
533 person responsible for a bug can see that A was executed, and then B and
534 then C, knowing that sequence of events might trigger the realization of
535 an intermediate step that was missing, or an extra step that might have
536 changed the environment enough to cause a visible problem. Again,
537 restraint is always in order (``I set the build running, went to get a
538 cup of coffee (Columbian, cream but no sugar), talked to Sheila on the
539 phone, and then THIS happened@dots{}'') but be sure to include anything
543 Richard Stallman writes, ``The fundamental principle of reporting bugs
544 usefully is this: @strong{report all the facts}. If you are not sure
545 whether to state a fact or leave it out, state it!'' This holds true
546 across all problem reporting systems, for computer software or social
547 injustice or motorcycle maintenance. It is especially important in the
548 software field due to the major differences seemingly insignificant
549 changes can make (a changed variable, a missing semicolon, etc.).
552 Submit only @emph{one} problem with each Problem Report. If you have
553 multiple problems, use multiple PRs. This aids in tracking each problem
554 and also in analyzing the problems associated with a given program.
557 It never hurts to do a little research to find out if the bug you've
558 found has already been reported. Most software releases contain lists
559 of known bugs in the Release Notes which come with the software; see
560 your system administrator if you don't have a copy of these.
563 The more closely a PR adheres to the standard format, the less
564 interaction is required by a database administrator to route the
565 information to the proper place. Keep in mind that anything that
566 requires human interaction also requires time that might be better spent
567 in actually fixing the problem. It is therefore in everyone's best
568 interest that the information contained in a PR be as correct as
569 possible (in both format and content) at the time of submission.