2. Editing and sending PRs

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

2.1 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 section 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 section Problem Report format. Also see Helpful hints.)

For examples of a Problem Report template and complete Problem Report, see 3. An Example.

The default template contains your preconfigured `>Submitter-Id:'. send-pr attempts to determine values for the `>Originator:' and `>Organization:' fields (see section Problem Report format). send-pr will set the `>Originator:' field to the value of the NAME environment variable if it has been set; similarly, `>Organization:' will be set to the value of ORGANIZATION. 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. (See section Setting a default site.)

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. A complete sample bug report, from template to completed PR, is shown in 3. An Example. For a complete list of valid categories, type `send-pr -L' at your prompt. See section Valid Categories, for a sample list of categories, .

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 3.101

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 section 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 (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:'.

Your copy of send-pr should have already been customized on installation to reflect your `>Submitter-Id:'. (See section Installing send-pr on your system.) If you don't know your `>Submitter-Id:', you can request it using `send-pr --request-id'. If your organization is not affiliated with the site you send Problem Reports to, a good generic `>Submitter-Id:' to use is `net'.

If your PR has an invalid value in one of the ENUMERATED fields (see section 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.

2.2 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 section `Introduction' in GNU Emacs).

Call send-pr with `M-x send-pr'.(1) 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. See section 3. An Example, for a sample Problem Report.

`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 section `Introduction' in GNU Emacs.

2.3 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. (See section Setting a default site.)

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.

-c mail-address

--cc mail-address

Places mail-address in the Cc: header field of the message to be sent.

--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.

-s severity

--severity severity

Sets the initial value of the >Severity: field to severity.

-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.

2.4 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 section `Reporting Bugs' in 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.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.