You can invoke send-pr from a shell prompt or from within GNU Emacs using M-x send-pr.

Creating new Problem Reports
============================

Invoking send-pr presents a PR template with a number of fields already filled in.  Complete the template as thoroughly as possible to make a useful bug report.  Submit only one bug with each PR.

A template consists of three sections:

Comments
     The top several lines of a blank template consist of a series of comments that provide some basic instructions for completing the Problem Report, as well as a list of valid entries for the >Category: field.  These comments are all preceded by the string SEND-PR: and are erased automatically when the PR is submitted.  The instructional comments within < and > are also removed. (Only these comments are removed; lines you provide that happen to have those characters in them, such as examples of shell-level redirection, are not affected.)

Mail Header
     send-pr creates a standard mail header.  send-pr completes all fields except the Subject: line with default values. (see Problem Report format.)

GNATS fields
     These are the informational fields that GNATS uses to route your Problem Report to the responsible party for further action.  They should be filled out as completely as possible.  (see Problem Report format.  Also see Helpful hints.)

The default template contains your preconfigured >Submitter-Id:. send-pr attempts to determine values for the >Originator: and >Organization: fields (see Problem Report format).  send-pr also attempts to find out some information about your system and architecture, and places this information in the >Environment: field if it finds any.

You may submit problem reports to different Support Sites from the default site by specifying the alternate site when you invoke send-pr.  Each site has its own list of categories for which it accepts Problem Reports.

send-pr also provides the mail header section of the template with default values in the To:, From:, and Reply-To: fields.  The Subject: field is empty.

The template begins with a comment section:

     SEND-PR: -*- send-pr  -*-
     SEND-PR: Lines starting with `SEND-PR' will be removed
     SEND-PR: automatically as well as all comments (the text
     SEND-PR: below enclosed in `<' and `>').
     SEND-PR:
     SEND-PR: Please consult the document `Reporting Problems
     SEND-PR: Using send-pr' if you are not sure how to fill out
     SEND-PR: a problem report.
     SEND-PR:
     SEND-PR: Choose from the following categories:

and also contains a list of valid >Category: values for the Support Site to whom you are submitting this Problem Report.  One (and only one) of these values should be placed in the >Category: field.

The mail header is just below the comment section.  Fill out the Subject: field, if it is not already completed using the value of >Synopsis:.  The other mail header fields contain default values.

     To: SUPPORT-SITE
     Subject: complete this field
     From: YOUR-LOGIN@YOUR-SITE
     Reply-To: YOUR-LOGIN@YOUR-SITE
     X-send-pr-version: send-pr VERSION

where SUPPORT-SITE is an alias for the Support Site you wish to submit this PR to.

The rest of the template contains GNATS fields.  Each field is either automatically completed with valid information (such as your >Submitter-Id:) or contains a one-line instruction specifying the information that field requires in order to be correct.  For example, the >Confidential: field expects a value of yes or no, and the answer must fit on one line; similarly, the >Synopsis: field expects a short synopsis of the problem, which must also fit on one line.  Fill out the fields as completely as possible.  See Helpful hints, for suggestions as to what kinds of information to include.

In this example, words in italics are filled in with pre-configured information:

     >Submitter-Id: your submitter-id
     >Originator:   your name here
     >Organization:
         your organization
     >Confidential:<[ yes | no ] (one line)>
     >Synopsis:    <synopsis of the problem (one line)>
     >Severity:    <[non-critical | serious | critical](one line)>
     >Priority:    <[ low | medium | high ] (one line)>
     >Category:    <name of the product (one line)>
     >Class:       <[sw-bug | doc-bug | change-request | support]>
     >Release:     <release number or tag (one line)>
     >Environment:
              <machine, os, target, libraries (multiple lines)>

     >Description:
            <precise description of the problem (multiple lines)>
     >How-To-Repeat:
            <code/input/activities to reproduce (multiple lines)>
     >Fix:
            <how to correct or work around the problem, if known
             (multiple lines)>

When you finish editing the Problem Report, send-pr mails it to the address named in the To: field in the mail header. send-pr checks that the complete form contains a valid >Category:.

If your PR has an invalid value in one of the ENUMERATED fields (see Problem Report format), send-pr places the PR in a temporary file named /tmp/pbadNNNN on your machine. NNNN is the process identification number given to your current send-pr session.  If you are running send-pr from the shell, you are prompted as to whether or not you wish to try editing the same Problem Report again.  If you are running send-pr from Emacs, the Problem Report is placed in the buffer *send-pr-error*; you can edit this file and then submit it with

     M-x gnats-submit-pr

Any further mail concerning this Problem Report should be carbon-copied to the GNATS mailing address as well, with the category and identification number in the Subject: line of the message.

     Subject: Re: PR CATEGORY/GNATS-ID: ORIGINAL MESSAGE SUBJECT

Messages which arrive with Subject: lines of this form are automatically appended to the Problem Report in the >Audit-Trail: field in the order received.

Using send-pr from within Emacs
===============================

You can use an interactive send-pr interface from within GNU Emacs to fill out your Problem Report.  We recommend that you familiarize yourself with Emacs before using this feature (see Introduction (GNU Emacs)).

Call send-pr with M-x send-pr. (If typing M-x send-pr doesn't work, see your system administrator for help loading send-pr into Emacs.)  send-pr responds with a Problem Report template preconfigured for the Support Site from which you received send-pr.  (If you use send-pr locally, the default Support Site is probably your local site.)

You may also submit problem reports to different Support Sites from the default site.  To use this feature, invoke send-pr with

     C-u M-x send-pr

send-pr prompts you for the name of a SITE.  SITE is an alias on your local machine which points to an alternate Support Site.

send-pr displays the template and prompts you in the minibuffer with the line:

     >Category: other

Delete the default value other in the minibuffer and replace it with the keyword corresponding to your problem (the list of valid categories is in the topmost section of the PR template).  For example, if the problem you wish to report has to do with the GNU C compiler, and your support organization accepts bugs submitted for this program under the category gcc, delete other and then type gcc[RET].  send-pr replaces the line

     >Category:       <name of the product (one line)>

in the template with

     >Category:       gcc

and moves on to another field.

send-pr provides name completion in the minibuffer.  For instance, you can also type gc[TAB], and send-pr attempts to complete the entry for you.  Typing g[TAB] may not have the same effect if several possible entries begin with g.  In that case send-pr cannot complete the entry because it cannot determine whether you mean gcc or, for example, gdb, if both of those are possible categories. send-pr continues to prompt you for a valid entry until you enter one.

send-pr prompts you interactively to enter each field for which there is a range of specific choices.  If you attempt to enter a value which is not in the range of acceptable entries, send-pr responds with [No match] and allows you to change the entry until it contains an acceptable value.  This avoids unusable information (at least in these fields) and also avoids typographical errors which could cause problems later.

send-pr prompts you for the following fields:

     >Category:
     >Confidential: (default:  no)
     >Severity:     (default:  serious)
     >Priority:     (default:  medium)
     >Class:        (default:  sw-bug)
     >Release:
     >Synopsis:     (this value is copied to Subject:)

After you complete these fields, send-pr places the cursor in the >Description: field and displays the message

     To send the problem report use: C-c C-c

in the minibuffer.  At this point, edit the file in the main buffer to reflect your specific problem, putting relevant information in the proper fields.

send-pr provides a few key bindings to make moving around in a template buffer more simple:

C-c C-f
M-x change-field
     Changes the field under the cursor.  edit-pr prompts you for a new value.

M-C-b
M-x gnats-backward-field
     Moves the cursor to the beginning of the value of the current field.

M-C-f
M-x gnats-forward-field
     Moves the cursor to the end of the value of the current field.

M-p
M-x gnats-previous-field
     Moves the cursor back one field to the beginning of the value of the previous field.

M-n
M-x gnats-next-field
     Moves the cursor forward one field to the beginning of the value of the next field.

send-pr takes over again when you type C-c C-c to send the message.  send-pr reports any errors in a separate buffer, which remains in existence until you send the PR properly (or, of course, until you explicitly kill the buffer).

For detailed instructions on using Emacs, see Introduction (GNU Emacs).

Invoking send-pr from the shell
===============================

     send-pr [ SITE ]
             [ -f PROBLEM-REPORT | --file PROBLEM-REPORT ]
             [ -t MAIL-ADDRESS | --to MAIL-ADDRESS ]
             [ --request-id ]
             [ -L | --list ] [ -P | --print ]
             [ -V | --version] [ -h | --help ]

SITE is an alias on your local machine which points to an address used by a Support Site.  If this argument is not present, the default SITE is usually the site which you received send-pr from, or your local site if you use GNATS locally.

Invoking send-pr with no options calls the editor named in your environment variable EDITOR on a default PR template.  If the environment variable PR_FORM is set, its value is used as a file name which contains a valid template.  If PR_FORM points to a missing or unreadable file, or if the file is empty, send-pr generates an error message and opens the editor on a default template.

-f PROBLEM-REPORT
--file PROBLEM-REPORT
     Specifies a file, PROBLEM-REPORT, where a completed Problem Report already exists.  send-pr sends the contents of the file without invoking an editor.  If PROBLEM-REPORT is -, send-pr reads from standard input.

-t MAIL-ADDRESS
--to MAIL-ADDRESS
     Sends the PR to MAIL-ADDRESS. The default is preset when send-pr is configured.  This option is not recommended; instead, use the argument SITE on the command line.

--request-id
     Sends a request for a >Submitter-Id: to the Support Site.

-L

--list
     Prints the list of valid >Category: values on standard output. No mail is sent.

-P
--print
     Displays the PR template.  If the variable PR_FORM is set in your environment, the file it specifies is printed.  If PR_FORM is not set, send-pr prints the standard blank form.  If the file specified by PR_FORM doesn't exist, send-pr displays an error message.  No mail is sent.

-V
--version
     Displays the send-pr version number and a usage summary.  No mail is sent.

-h
--help
     Displays a usage summary for send-pr.  No mail is sent.

Helpful hints
=============

There is no orthodox standard for submitting effective bug reports, though you might do well to consult the section on submitting bugs for GNU gcc in Reporting Bugs (Using and Porting GNU CC), by Richard Stallman.  This section contains instructions on what kinds of information to include and what kinds of mistakes to avoid.

In general, common sense (assuming such an animal exists) dictates the kind of information that would be most helpful in tracking down and resolving problems in software.

  * Include anything you would want to know if you were looking at the report from the other end.  There's no need to include every minute detail about your environment, although anything that might be different from someone else's environment should be included (your path, for instance).

  * Narratives are often useful, given a certain degree of restraint.  If a person responsible for a bug can see that A was executed, and then B and then C, knowing that sequence of events might trigger the realization of an intermediate step that was missing, or an extra step that might have changed the environment enough to cause a visible problem.  Again, restraint is always in order (``I set the build running, went to get a cup of coffee (Columbian, cream but no sugar), talked to Sheila on the phone, and then THIS happened...'') but be sure to include anything relevant.

  * Richard Stallman writes, ``The fundamental principle of reporting bugs usefully is this: report all the facts.  If you are not sure whether to state a fact or leave it out, state it!''  This holds true across all problem reporting systems, for computer software or social injustice or motorcycle maintenance.  It is especially important in the software field due to the major differences seemingly insignificant changes can make (a changed variable, a missing semicolon, etc.).

  * Submit only one problem with each Problem Report.  If you have multiple problems, use multiple PRs.  This aids in tracking each problem and also in analyzing the problems associated with a given program.

  * It never hurts to do a little research to find out if the bug you've found has already been reported.  Most software releases contain lists of known bugs in the Release Notes which come with the software; see your system administrator if you don't have a copy of these.

  * The more closely a PR adheres to the standard format, the less interaction is required by a database administrator to route the information to the proper place.  Keep in mind that anything that requires human interaction also requires time that might be better spent in actually fixing the problem.  It is therefore in everyone's best interest that the information contained in a PR be as correct as possible (in both format and content) at the time of submission.