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