Node:using send-pr, Next:, Up:send-pr


The Problem Report template

Invoking send-pr presents a PR template with a number of fields already filled in with default values for the database you are submitting to. 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:

The Comments section at the top of the template contains basic instructions for completing the Problem Report, as well as a list of valid entries for the Category field. One (and only one) of these values should be placed in the Category field further down in the Problem Report. 

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:

The comments lines 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.)

The Mail Header section of the template contains a standard mail header constructed by send-pr. send-pr can be set up to submit PRs by e-mail or by speaking directly to the GNATS server, but since this header is part of the standard format of Problem Reports, send-pr includes it even when it is set up to speak directly to the server. 

To: PR submission address
Subject: complete this field
From: your-login@your-site
Reply-To: your-login@your-site
X-send-pr-version: send-pr 4.0-prebeta2

send-pr automatically completes all the mail header fields except the Subject line with default values. (See Problem Report format.)

The GNATS fields below the mail header form the bulk of a GNATS Problem Report.

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.

The mechanisms send-pr uses to fill in default values is as follows: Your preconfigured Submitter-Id is taken from the local send-pr.conf configuration file. 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. If these variables aren't set in you environment, send-pr uses the values set in the local send-pr.conf configuration file, if that exists. If not, these values are left blank in the template. 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.

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 validates the contents and if it looks OK either submits it directly to the GNATS server or submits it by mail to the address named in the To field in the mail header.

If your PR contains one or more invalid field values, 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 *gnats-send*; you can edit this file and then submit it with C-c C-c.

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 they are received.