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: Fields.)

"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.  (*Note Problem
     Report format: Fields.  Also see See Helpful hints: Helpful hints.)

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

   The default template contains your preconfigured `>Submitter-Id:'.
`send-pr' attempts to determine values for the `>Originator:' and
`>Organization:' fields (see Problem Report format: Fields.).
`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 Setting a default SITE: 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
See An Example.  For a complete list of valid categories, type
`send-pr -L' at your prompt.  See Valid Categories: 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.2

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

   Your copy of `send-pr' should have already been customized on
installation to reflect your `>Submitter-Id:'.  (*Note Installing
`send-pr' on your system: Installing send-pr.)  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'. *NOTE:* If
you are using send-pr to send problem reports to the FreeBSD Project,
this version of send-pr already has a customer ID in it and you do not
need to request a new one.

   If your PR has an invalid value in one of the ENUMERATED fields
(see Problem Report format: Fields.), `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.