1You can invoke @code{send-pr} from a shell prompt, or from within 2@sc{gnu} Emacs using @w{@samp{M-x send-pr}} (@pxref{Emacs 3submitting,,Submitting Problem Reports from Emacs}.) 4 5@menu 6* PR template:: The Problem Report template 7* send-pr in Emacs:: Using send-pr from within Emacs 8* send-pr from the shell:: Invoking send-pr from the shell 9* Submitting via e-mail:: Submitting a Problem Report via direct e-mail 10* Helpful hints:: 11@end menu 12 13@node send-pr from the shell 14@section Invoking @code{send-pr} from the shell 15@cindex command line options 16@cindex invoking @code{send-pr} from the shell 17@cindex shell invocation 18 19@smallexample 20send-pr [ -b | --batch ] 21 [ -d @var{database} | --database @var{database} ] 22 [ -f @var{file} | --file @var{file} ] 23 [ -p | --print ] [ --request-id ] 24 [ -s @var{severity} | --severity @var{severity} ] 25 [ -V | --version ] [ -h | --help ] 26@end smallexample 27 28Invoking @code{send-pr} with no options assumes that you want to 29submit to the local @sc{gnats} database named @var{default} and calls 30the editor named in your environment variable @code{EDITOR} on a PR 31template for this database. 32 33@table @code 34@item -b 35@itemx --batch 36Suppresses printing of most of the messages @code{send-pr} usually 37prints while running. 38 39@item -d @var{database}, --database @var{database} 40Specifies the database to which the PR is to be submitted; if no 41database is specified, the local database named @code{default} is 42assumed. This option overrides the database specified in the 43@code{GNATSDB} environment variable. @var{database} can also be set 44to a remote database by using the format for @code{GNATSDB} described 45in @ref{Environment,,Environment variables and @sc{gnats} tools}. 46 47@item -f @var{problem-report} 48@itemx --file @var{problem-report} 49Specifies a file, @var{problem-report}, where a completed Problem 50Report or a PR template exists. @code{send-pr} verifies that the 51contents of the file constitute a valid PR and asks you if you want to 52edit it or send it directly. If the PR text is invalid you will be 53told what is wrong and be given the option to edit it. If 54@var{problem-report} is @samp{-}, @w{@code{send-pr}} reads from 55standard input. 56 57@item -p 58@itemx --print 59Displays the PR template for the specified database, or if the 60@code{-d} or @code{--database} options aren't specified, print the 61template for the local @var{default} database. No PR is submitted. 62 63@item --request-id 64Sends a request for a @code{Submitter-Id} to the Support Site. 65 66@item -s @var{severity} 67@itemx --severity @var{severity} 68@cindex @code{send-pr} fields 69Sets the initial value of the @code{Severity} field to @var{severity}. 70 71@item -V 72@itemx --version 73Displays the @code{send-pr} version number and a usage summary. No mail 74is sent. 75 76@item -h 77@itemx --help 78Displays a usage summary for @code{send-pr}. No mail is sent. 79@end table 80 81@c --------------------------------------------------------------- 82@node send-pr in Emacs 83@section Using @code{send-pr} from within Emacs 84@cindex using @code{send-pr} from within Emacs 85@cindex @code{send-pr} within Emacs 86@cindex invoking @code{send-pr} from Emacs 87@cindex interactive interface 88 89You can use an interactive @code{send-pr} interface from within @sc{gnu} 90Emacs to fill out your Problem Report. We recommend that you 91familiarize yourself with Emacs before using this feature 92(@pxref{Introduction,,Introduction,emacs,GNU Emacs}). 93 94Call @code{send-pr} with @w{@samp{M-x send-pr}}.@footnote{If typing 95@w{@samp{M-x send-pr}} doesn't work, see your system administrator for 96help loading @file{gnats.el} into Emacs.} @code{send-pr} responds 97with a preconfigured Problem Report template. The Emacs interface is 98described in more detail in a separate section, @xref{Emacs,,The Emacs 99interface to @sc{gnats}}. 100 101@node PR template 102@section The Problem Report template 103 104Invoking @code{send-pr} presents a PR @dfn{template} with a number of 105fields already filled in with default values for the database you are 106submitting to. Complete the template as thoroughly as possible to 107make a useful bug report. Submit only one bug with each PR. 108 109@cindex template 110A template consists of three sections: 111 112@itemize @bullet 113@item Comments 114@item Mail Header 115@item @sc{gnats} fields 116@end itemize 117 118The @strong{Comments section} at the top of the template contains basic 119instructions for completing the Problem Report, as well as a list of 120valid entries for the @code{Category} field. One (and only one) of 121these values should be placed in the @code{Category} field further down 122in the Problem Report. 123 124@cindex template comment section 125@cindex comment section in the PR template 126@smallexample 127@group 128SEND-PR: -*- send-pr -*- 129SEND-PR: Lines starting with `SEND-PR' will be removed 130SEND-PR: automatically as well as all comments (the text 131SEND-PR: below enclosed in `<' and `>'). 132SEND-PR: 133SEND-PR: Please consult the document `Reporting Problems 134SEND-PR: Using send-pr' if you are not sure how to fill out 135SEND-PR: a problem report. 136SEND-PR: 137SEND-PR: Choose from the following categories: 138@end group 139@end smallexample 140 141@ifset SENDPR 142A complete sample bug report, from template to completed PR, is shown in 143@ref{An Example}. For a complete list of valid categories, type 144@w{@samp{send-pr -L}} at your prompt. @xref{Valid Categories,,Valid 145Categories}, for a sample list of categories, . 146@end ifset 147 148The comments lines are all preceded by the string @samp{SEND-PR:} and 149are erased automatically when the PR is submitted. The instructional 150comments within @samp{<} and @samp{>} are also removed. (Only these 151comments are removed; lines you provide that happen to have those 152characters in them, such as examples of shell-level redirection, are not 153affected.) 154 155The @strong{Mail Header} section of the template contains a standard 156mail header constructed by @code{send-pr}. @code{send-pr} can be set up 157to submit PRs by e-mail or by speaking directly to the @sc{gnats} 158server, but since this header is part of the standard format of Problem 159Reports, @code{send-pr} includes it even when it is set up to speak 160directly to the server. 161 162@cindex mail header section 163@smallexample 164@group 165To: @var{PR submission address} 166Subject: @emph{complete this field} 167From: @var{your-login}@@@var{your-site} 168Reply-To: @var{your-login}@@@var{your-site} 169X-send-pr-version: send-pr @value{VERSION} 170@end group 171@end smallexample 172 173@noindent 174@code{send-pr} automatically completes all the mail header fields except 175the @code{Subject} line with default values. (@xref{Fields,,Problem 176Report format}.) 177 178The @strong{@sc{gnats} fields} below the mail header form the bulk of a 179@sc{gnats} Problem Report. 180 181Each field is either automatically completed with valid information 182(such as your @code{Submitter-Id}) or contains a one-line instruction 183specifying the information that field requires in order to be correct. 184For example, the @code{Confidential} field expects a value of @samp{yes} 185or @samp{no}, and the answer must fit on one line; similarly, the 186@code{Synopsis} field expects a short synopsis of the problem, which 187must also fit on one line. Fill out the fields as completely as 188possible. @xref{Helpful hints,,Helpful hints}, for suggestions as to 189what kinds of information to include. 190 191The mechanisms @code{send-pr} uses to fill in default values is as 192follows: Your preconfigured @code{Submitter-Id} is taken from the local 193@file{send-pr.conf} configuration file. @code{send-pr} will set the 194@code{Originator} field to the value of the @code{NAME} environment 195variable if it has been set; similarly, @code{Organization} will be set 196to the value of @code{ORGANIZATION}. If these variables aren't set in 197you environment, @code{send-pr} uses the values set in the local 198@file{send-pr.conf} configuration file, if that exists. If not, these 199values are left blank in the template. @code{send-pr} also attempts to 200find out some information about your system and architecture, and places 201this information in the @code{Environment} field if it finds any. 202 203In this example, words in @emph{italics} are filled in with 204pre-configured information: 205 206@cindex @code{send-pr} fields 207@smallexample 208>Submitter-Id: @emph{your submitter-id} 209>Originator: @emph{your name here} 210>Organization: 211 @emph{your organization} 212>Confidential:<[ yes | no ] (one line)> 213>Synopsis: <synopsis of the problem (one line)> 214>Severity: <[non-critical | serious | critical](one line)> 215>Priority: <[ low | medium | high ] (one line)> 216>Category: <name of the product (one line)> 217>Class: <[sw-bug | doc-bug | change-request | support]> 218>Release: <release number (one line)> 219>Environment: 220 <machine, os, target, libraries (multiple lines)> 221 222>Description: 223 <precise description of the problem (multiple lines)> 224>How-To-Repeat: 225 <code/input/activities to reproduce (multiple lines)> 226>Fix: 227 <how to correct or work around the problem, if known 228 (multiple lines)> 229@end smallexample 230 231@cindex @code{Submitter-Id} field 232@cindex @code{>Submitter-Id} 233When you finish editing the Problem Report, @code{send-pr} validates the 234contents and if it looks OK either submits it directly to the 235@sc{gnats} server or submits it by mail to the address named in the 236@code{To} field in the mail header. 237 238@cindex bad Problem Reports 239@cindex errors 240@cindex invalid Problem Reports 241If your PR contains one or more invalid field values, @code{send-pr} 242places the PR in a temporary file named @file{/tmp/pbad@var{nnnn}} on 243your machine. @var{nnnn} is the process identification number given 244to your current @code{send-pr} session. If you are running 245@code{send-pr} from the shell, you are prompted as to whether or not 246you wish to try editing the same Problem Report again. If you are 247running @code{send-pr} from Emacs, the Problem Report is placed in the 248buffer @w{@samp{*gnats-send*}}; you can edit this file and then submit 249it with @kbd{C-c C-c}. 250 251@c ------------------------------------------------------------------------- 252@node Submitting via e-mail 253@section Submitting a Problem Report via direct e-mail 254@cindex Direct e-mail 255@cindex Submitting a PR via e-mail 256In addition to using @code{send-pr}, there is another way to submit a 257problem report. You can simply send an e-mail message to the PR 258submission e-mail address of the support site (This address should be 259published by the support site.) 260 261When you send unformatted e-mail to this address, @sc{gnats} processes 262the message as a new problem report, filling in as many fields from 263defaults as it can: 264 265@table @code 266@item Synopsis 267The @code{Synopsis} field is filled in by the @code{Subject} header of 268the e-mail message. 269 270@item Submitter ID 271@sc{gnats} will try to derive the @code{Submitter} field from the address 272in the @code{From} header of the e-mail. 273 274@item Description 275All of the text in the body of the e-mail message is put into the 276@code{Description} field. 277@end table 278 279Other fields, such as @code{Category}, @code{Version}, @code{Severity}, 280etc. are set to default values as defined by the @sc{gnats} administrator. 281 282@c -------------------------------------------------------------------------- 283@node Helpful hints 284@section Helpful hints 285@cindex helpful hints 286@cindex Using and Porting @sc{gnu} CC 287@cindex effective problem reporting 288@cindex kinds of helpful information 289@cindex information to submit 290@cindex Report all the facts! 291 292There is no orthodox standard for submitting effective bug reports, 293though you might do well to consult the section on submitting bugs for 294@sc{gnu} @code{gcc} in @ref{Bugs, , Reporting Bugs, gcc, Using and 295Porting GNU CC}, by Richard Stallman. This section contains 296instructions on what kinds of information to include and what kinds of 297mistakes to avoid. 298 299In general, common sense (assuming such an animal exists) dictates the 300kind of information that would be most helpful in tracking down and 301resolving problems in software. 302@itemize @bullet 303@item 304Include anything @emph{you} would want to know if you were looking at 305the report from the other end. There's no need to include every minute 306detail about your environment, although anything that might be different 307from someone else's environment should be included (your path, for 308instance). 309 310@item 311Narratives are often useful, given a certain degree of restraint. If a 312person responsible for a bug can see that A was executed, and then B and 313then C, knowing that sequence of events might trigger the realization of 314an intermediate step that was missing, or an extra step that might have 315changed the environment enough to cause a visible problem. Again, 316restraint is always in order (``I set the build running, went to get a 317cup of coffee (Columbian, cream but no sugar), talked to Sheila on the 318phone, and then THIS happened@dots{}'') but be sure to include anything 319relevant. 320 321@item 322Richard Stallman writes, ``The fundamental principle of reporting bugs 323usefully is this: @strong{report all the facts}. If you are not sure 324whether to state a fact or leave it out, state it!'' This holds true 325across all problem reporting systems, for computer software or social 326injustice or motorcycle maintenance. It is especially important in the 327software field due to the major differences seemingly insignificant 328changes can make (a changed variable, a missing semicolon, etc.). 329 330@item 331Submit only @emph{one} problem with each Problem Report. If you have 332multiple problems, use multiple PRs. This aids in tracking each problem 333and also in analyzing the problems associated with a given program. 334 335@item 336It never hurts to do a little research to find out if the bug you've 337found has already been reported. Most software releases contain lists 338of known bugs in the Release Notes which come with the software; see 339your system administrator if you don't have a copy of these. 340 341@item 342The more closely a PR adheres to the standard format, the less 343interaction is required by a database administrator to route the 344information to the proper place. Keep in mind that anything that 345requires human interaction also requires time that might be better spent 346in actually fixing the problem. It is therefore in everyone's best 347interest that the information contained in a PR be as correct as 348possible (in both format and content) at the time of submission. 349@end itemize 350