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