A Problem Report is a message that describes a problem you are
having with a body of work. send-pr
organizes this message into
a form which can be understood and automatically processed by GNATS,
the GNU Problem Report Management System. A Problem Report is
organized into fields which contain data describing you, your
organization, and the problem you are announcing (see section Problem Report format). Problem Reports go through several defined states in
their lifetimes, from open to closed (see section States of Problem Reports).
Each PR goes through a defined series of states between origination and closure. The originator of a PR receives notification automatically of any state changes.
The format of a PR is designed to reflect the nature of GNATS as a database. Information is arranged into fields, and kept in individual records (Problem Reports).
Problem Report fields are denoted by a keyword which begins with `>' and ends with `:', as in `>Confidential:'. Fields belong to one of three data types:
send-pr
template as a comment.
The following fields are ENUMERATED format; see the descriptions of
fields below for explanations of each field in detail:
>Confidential: >Severity: >Priority: >Class: >State: >Number:
>Submitter-Id: >Originator: >Synopsis: >Category: >Release: >Responsible: >Arrival-Date:
>Organization: >Environment: >Description: >How-To-Repeat: >Fix: >Audit-Trail: >Unformatted:
A Problem Report contains two different types of fields: Mail Header fields, which are used by the mail handler for delivery, and Problem Report fields, which contain information relevant to the Problem Report and its submitter. A Problem Report is essentially a specially formatted electronic mail message.
The following is an example Problem Report. Mail headers are at the top, followed by GNATS fields, which begin with `>' and end with `:'. The `Subject:' line in the mail header and the `>Synopsis:' field are usually duplicates of each other.
Message-Id: message-id Date: date From: address Reply-To: address To: bug-address Subject: subject >Number: gnats-id >Category: category >Synopsis: synopsis >Confidential: yes or no >Severity: 1a, 1b, 2a, 2b, 3a, 3b, 4a, 4b, or 5 >Priority: high, medium or low >Responsible: responsible >State: open, analyzed, suspended, feedback, or closed >Class: A, B, C, D, E, F, G, H, or I >Submitter-Id: submitter-id >Arrival-Date: date >Originator: name >Organization: organization >Release: release >Environment: environment >Description: description >How-To-Repeat: how-to-repeat >Fix: fix >Audit-Trail: appended-messages... State-Changed-From-To: from-to State-Changed-When: date State-Changed-Why: reason Responsible-Changed-From-To: from-to Responsible-Changed-When: date Responsible-Changed-Why: reason >Unformatted: miscellaneous
A Problem Report may contain any mail header field described in the
Internet standard RFC-822. However, only the fields which identify the
sender and the subject are required by send-pr
:
To:
send-pr
.
Subject:
From:
Reply-To:
From:
field.
The following fields are present whenever a PR is submitted via the
program send-pr
. GNATS adds additional fields when the PR
arrives at the Support Site; explanations of these follow this list.
>Submitter-Id:
send-pr
with the `--request-id' option to apply for one from
the support organization. Problem Reports from those not affiliated
with the support organization should use the default value of `net'
for this field.)
>Originator:
NAME
.
>Organization:
DEFAULT_ORGANIZATION
in the
send-pr
shell script.
>Confidential:
>Synopsis:
send-pr
copies
this information to the `Subject:' line when you submit a Problem
Report.
>Severity:
1a
1b
2a
2b
3a
3b
4a
4b
5
>Priority:
high
medium
low
>Category:
fmd
fmd.ui.tcl
hdf2pdb
hdfdump
libdfftpack
libfmm3d
quanta2fmd
send-pr
test
other
>Class:
A
B
C
D
E
F
G
H
I
>Release:
>Environment:
>Description:
>How-To-Repeat:
>Fix:
GNATS adds the following fields when the PR arrives at the Support Site:
>Number:
category/numberin subsequent email messages. This is for historical reasons, as well as because Problem Reports are stored in subdirectories which are named by category.
>State:
open
analyzed
feedback
closed
suspended
>Responsible:
>Arrival-Date:
>Audit-Trail:
State-Changed-<From>-<To>: oldstate>-<newstate
Responsible-Changed-<From>-<To>: oldresp>-<newresp
State-Changed-By: name
Responsible-Changed-By: name
State-Changed-When: timestamp
Responsible-Changed-When: timestamp
State-Changed-Why: reason...
Responsible-Changed-Why: reason...
>Unformatted:
You can invoke send-pr
from a shell prompt or from within
GNU Emacs using `M-x send-pr'.
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:
send-pr
creates a standard mail header. send-pr
completes
all fields except the `Subject:' line with default values.
(See section Problem Report format.)
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
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 list of valid categories can be obtained by typing
`send-pr -L' at your prompt.
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 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: <[ 5 | 4b | 4a | 3b | 3a | 2b | 2a | 1b | 1a ](one line)> >Priority: <[ low | medium | high ] (one line)> >Category: <[ fmd | fmd.ui.tcl | hdf2pdb | ... ] (one line)> >Class: <[ A | B | C | D | E | F | G | H | I ] (one line)> >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:'. (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.
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: 3b)
>Priority: (default: medium)
>Class: (default: E)
>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
edit-pr
prompts you for a
new value.
M-C-b
M-x gnats-backward-field
M-C-f
M-x gnats-forward-field
M-p
M-x gnats-previous-field
M-n
M-x gnats-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.
send-pr
from the shellsend-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
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
send-pr
is configured. This option is not recommended;
instead, use the argument site on the command line.
--request-id
>Submitter-Id:
to the Support Site.
-L
--list
>Category:
values on standard output.
No mail is sent.
-P
--print
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
send-pr
version number and a usage summary. No mail
is sent.
-h
--help
send-pr
. No mail is sent.
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.
The FMD development team maintains a database of all PR's received. This database can be queried via e-mail. This service can be used to get immediate status update on PR's without waiting for a team member to respond. The only constraint is that confidential reports can not be accessed.
An e-mail query consists of only a `To:' and a `Subject:' line. The body of the e-mail is ignored and may be left blank (unless your mailer insists on having some content to send). For example:
To: query-pr@feynman.ml.wpafb.af.mil Subject: fmd/1
would return a report on PR number 1 in category `fmd'.
Various options are allowed on the `Subject:' line which can narrow, or otherwise refine the type of reports returned. The options are used to specify the contents of various fields in the PR's. Only PR's with field contents that match the search options will be included in the query report. The accepted options are:
-c category
-s state
-r responsible
-S submitter
-e severity
-p priority
-O name
-F
By default, all PR's with `>State:' field values of `closed' are ignored. Thus one must add a `-s closed' option to retrive information on PR's that have been closed. Multiple query options are automatically AND'ed together (ie. all fields must match those specified).
It is possible to specify more than one value for a field. To do this, one builds a string, using "|" characters to separation values. For instance, if one wished to include PR's with `open' or `suspended' states, one would use an option that looked like:
To: query-pr@feynman.ml.wpafb.af.mil Subject: -s open|suspended -c fmd
A resulting default summary for the PR would look like:
>Number: 8 >Category: fmd >Synopsis: Improper caching of HPF configuration variable >Confidential: no >Severity: 4b >Priority: medium >Responsible: jim (Jim Lupo) >State: closed >Class: code >Submitter-Id: (n/a) >Originator: James A. Lupo >Release: (n/a) >Arrival-Date: Tue Apr 28 11:40:02 1998
A full report might be obtained with a query such as:
To: query-pr@feynman.ml.wpafb.af.mil Subject: -F -s closed -c fmd 1
The resulting report would look like:
>From lupoja Tue Apr 28 10:55:13 1998 Received: by feynman.ml.wpafb.af.mil (5.65v3.2/1.1.10.5/27May97-1042AM) id AA20262; Tue, 28 Apr 1998 10:55:13 -0400 Message-Id: <9804281455.AA20262@feynman.ml.wpafb.af.mil> Date: Tue, 28 Apr 1998 10:55:13 -0400 From: James A. Lupo <lupoja> Reply-To: lupoja To: af-gnats Subject: Memory leak X-Send-Pr-Version: 3.2 >Number: 1 >Category: fmd >Synopsis: Memory leak >Confidential: no >Severity: 2b >Priority: high >Responsible: jim (Jim Lupo) >State: closed >Class: code >Submitter-Id: (n/a) >Arrival-Date: Tue Apr 28 11:00:00 1998 >Originator: James A. Lupo >Organization: af >Release: (n/a) >Environment: System: OSF1 feynman.ml.wpafb.af.mil V4.0 464 alpha Machine: alpha >Description: Originally detected 97/02/15 Program crashes when models approaching maximum size are run. Symptoms change as instrumentation code is inserted, verifying memory leak, but not helping locate problem. >How-To-Repeat: Attempt to run very large models. >Fix: Originally closed 97/05/14 >Audit-Trail: State-Changed-From-To: open-closed State-Changed-By: lupoja State-Changed-When: Tue Apr 28 12:49:40 1998 State-Changed-Why: Entering old data into database for first time. >Unformatted:
send-pr
on your system
If you receive send-pr
as part of a larger software distribution,
it probably gets installed when the full distribution is installed. If
you are using GNATS at your site as well, you must decide where
send-pr
sends Problem Reports by default; see section Setting a default site.
send-pr
by itself
Install send-pr
by following these steps (you may need
root
access in order to change the `aliases' file and to
install send-pr
):
make all install [ info ] [ install-info ] [ clean ]The targets mean the following:
all
send-pr
and install-sid
install
install-sid
send-pr
send-pr.1
site
send-pr
, installed as
`prefix/lib/gnats/site'
send-pr.el
info (optional)
install-info (optional)
clean (optional)
install-sid your-sidwhere your-sid is the identification code you received with
send-pr
. send-pr
automatically inserts this value
into the template field `>Submitter-Id:'. If you've down loaded
send-pr
from the Net, use `net' for this value.
(autoload 'send-pr "send-pr" "Submit a Problem Report." t)
send-pr
, and for every site with which you wish to use
send-pr
to communicate. Each alias must have a suffix of
`-gnats'. The Support Site(s) will provide the correct addresses
where these aliases should point. For instance, edit your mail aliases
file to contain something like:
# support sites; for use with send-pr cygnus-gnats: bugs@cygnus.com # Cygnus Support bumblebee-gnats: bumblebugs@bumblebee.com # Bumblebee Inc. mycompany-gnats: bugs@my.company.com (if you use GNATS locally)
send-pr
automatically searches for these aliases when you type
send-pr cygnus send-pr bumblebee send-pr site...
send-pr
also uses site to determine the categories of
problems accepted by the site in question by looking in
prefix/lib/gnats/site
send-pr
is capable of sending Problem Reports to any number of
Support Sites, using mail aliases which have `-gnats' appended them.
send-pr
automatically appends the suffix, so that when you type
send-pr site
the Problem Report goes to the address noted in the `aliases' file
as `site-gnats'. You can do this in the Emacs version of
send-pr
by invoking the program with
C-u M-x send-pr
You are prompted for site.
site is also used to error-check the `>Category:' field, as a precaution against sending mistaken information (and against sending information to the wrong site).
You may also simply type
send-pr
from the shell (or `M-x send-pr' in Emacs), and the Problem
Report you generate will be sent to the site, which is usually the
site from which you received your distribution of send-pr
.
If you use GNATS at your own organization, the default is usually
your local address for reporting problems.
To change this, simply edit the file `Makefile' before installing and change the line
GNATS_SITE = site
to reflect the site where you wish to send PRs by default.
Jump to: > - a - b - c - d - e - f - g - h - i - k - l - m - n - o - p - q - r - s - t - u - v
>Arrival-Date:
>Audit-Trail:
>Category:
>Class:
>Confidential:
>Description:
>Environment:
>Fix:
>How-To-Repeat:
>Number:
>Organization:
>Originator:
>Priority:
>Release:
>Responsible:
>Severity:
>State:
>Submitter-Id:
, >Submitter-Id:
>Synopsis:
>Unformatted:
Arrival-Date
field
Audit-Trail
field
Category
field
Class
field
Confidential
field
Description
field
send-pr
Environment
field
Fix
field
From:
header
How-To-Repeat
field
send-pr
from Emacs
send-pr
from the shell
Number
field
Organization
field
Originator
field
Priority
field
Release
field
Reply-To:
header
Responsible
field
Responsible-Changed-<From>-<To>:
in >Audit-Trail:
Responsible-Changed-By:
in >Audit-Trail:
Responsible-Changed-When:
in >Audit-Trail:
Responsible-Changed-Why:
in >Audit-Trail:
send-pr
fields
send-pr
within Emacs
Severity
field
State
field
State-Changed-<From>-<To>:
in >Audit-Trail:
State-Changed-By:
in >Audit-Trail:
State-Changed-When:
in >Audit-Trail:
State-Changed-Why:
in >Audit-Trail:
Subject:
header
Submitter-Id
field, Submitter-Id
field
Synopsis
field
To:
header
Unformatted
field
send-pr
from within Emacs
This document was generated on 20 March 2000 using the texi2html translator version 1.52.