Go to the first, previous, next, last section, table of contents.
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 1.2 Problem Report format). Problem Reports go through several defined states in
their lifetimes, from open to closed (see section 1.1 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.
Unless your site has customized states (see @xref{states file,,,gnats}), GNATS uses these states:
- open
-
The initial state of a Problem Report. This means the PR has been filed
and the responsible person(s) notified.
- analyzed
-
The responsible person has analyzed the problem. The analysis should
contain a preliminary evaluation of the problem and an estimate of the
amount of time and resources necessary to solve the problem. It should
also suggest possible workarounds.
- feedback
-
The problem has been solved, and the originator has been given a patch
or other fix. The PR remains in this state until the originator
acknowledges that the solution works.
- closed
-
A Problem Report is closed ("the bug stops here") only when any
changes have been integrated, documented, and tested, and the submitter
has confirmed the solution.
- suspended
-
Work on the problem has been postponed. This happens if a timely
solution is not possible or is not cost-effective at the present time.
The PR continues to exist, though a solution is not being actively
sought. If the problem cannot be solved at all, it should be closed
rather than suspended.
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).
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.
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:
- ENUMERATED
-
One of a specific set of values, which vary according to the field. The
value for each keyword must be on the same line as the keyword. These
values are not configurable (yet).
For each ENUMERATED keyword, the possible choices are listed in the
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:
- TEXT
-
One single line of text which must begin and end on the same line (i.e.,
before a newline) as the keyword. See the descriptions of fields below
for explanations of each field in detail. The following fields are
TEXT format:
>Submitter-Id: >Originator: >Synopsis:
>Category: >Release: >Responsible:
>Arrival-Date:
- MULTITEXT
-
Text of any length may occur in this field. MULTITEXT may span
multiple lines and may also include blank lines. A MULTITEXT field
ends only when another keyword appears. See the descriptions of fields
below for explanations of each field in detail.
The following fields are MULTITEXT format:
>Organization: >Environment: >Description:
>How-To-Repeat: >Fix: >Audit-Trail:
>Unformatted:
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: critical, serious, or non-critical
>Priority: high, medium or low
>Responsible: responsible
>State: open, analyzed, suspended, feedback, or closed
>Class: sw-bug, doc-bug, change-request, support,
or duplicate
>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:
-
The preconfigured mail address for the Support Site where the PR is to
be sent, automatically supplied by
send-pr
.
Subject:
-
A terse description of the problem. This field normally contains the
same information as the `>Synopsis:' field.
From:
-
Usually supplied automatically by the originator's mailer; should
contain the originator's electronic mail address.
Reply-To:
-
A return address to which electronic replies can be sent; in most cases,
the same address as the
From:
field.
1.2.3 Field descriptions
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 them follow this list.
>Submitter-Id:
-
(TEXT) A unique identification code assigned by the Support Site.
It is used to identify all Problem Reports coming from a particular
site. (Submitters without a value for this field can invoke
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:
-
(TEXT) Originator's real name. The default is the value of the
originator's environment variable
NAME
.
>Organization:
-
(MULTITEXT) The originator's organization. The default value is
set with the variable
DEFAULT_ORGANIZATION
in the
send-pr
shell script.
>Confidential:
-
(ENUMERATED) Use of this field depends on the originator's
relationship with the support organization; contractual agreements often
have provisions for preserving confidentiality. Conversely, a lack of a
contract often means that any data provided will not be considered
confidential. Submitters should be advised to contact the support
organization directly if this is an issue.
If the originator's relationship to the support organization provides
for confidentiality, then if the value of this field is `yes' the
support organization treats the PR as confidential; any code samples
provided are not made publicly available (e.g., in regression test
suites). The default value is `yes'.
>Synopsis:
-
(TEXT) One-line summary of the problem.
send-pr
copies
this information to the `Subject:' line when you submit a Problem
Report.
>Severity:
-
(ENUMERATED) The severity of the problem. Accepted values include:
critical
-
The product, component or concept is completely non-operational or some
essential functionality is missing. No workaround is known.
serious
-
The product, component or concept is not working properly or significant
functionality is missing. Problems that would otherwise be considered
`critical' are rated `serious' when a workaround is known.
non-critical
-
The product, component or concept is working in general, but lacks
features, has irritating behavior, does something wrong, or doesn't
match its documentation.
The default value is `serious'.
>Priority:
-
(ENUMERATED) How soon the originator requires a solution. Accepted
values include:
high
-
A solution is needed as soon as possible.
medium
-
The problem should be solved in the next release.
low
-
The problem should be solved in a future release.
The default value is `medium'.
>Category:
-
(TEXT) The name of the product, component or concept where
the problem lies. The values for this field are defined by the Support
Site.
>Class:
-
(ENUMERATED) The class of a problem can be one of the following:
sw-bug
-
A general product problem. (`sw' stands for "software".)
doc-bug
-
A problem with the documentation.
change-request
-
A request for a change in behavior, etc.
support
-
A support problem or question.
duplicate (pr-number)
-
Duplicate PR. pr-number should be the number of the original PR.
The default is `sw-bug'.
>Release:
-
(TEXT) Release or version number of the product, component or
concept.
>Environment:
-
(MULTITEXT) Description of the environment where the problem occurred:
machine architecture, operating system, host and target types,
libraries, pathnames, etc.
>Description:
-
(MULTITEXT) Precise description of the problem.
>How-To-Repeat:
-
(MULTITEXT) Example code, input, or activities to reproduce the
problem. The support organization uses example code both to reproduce
the problem and to test whether the problem is fixed. Include all
preconditions, inputs, outputs, conditions after the problem, and
symptoms. Any additional important information should be included.
Include all the details that would be necessary for someone else to
recreate the problem reported, however obvious. Sometimes seemingly
arbitrary or obvious information can point the way toward a solution.
See also section 2.5 Helpful hints.
>Fix:
-
(MULTITEXT) A description of a solution to the problem, or a patch
which solves the problem. (This field is most often filled in at the
Support Site; we provide it to the submitter in case she has solved the
problem.)
GNATS adds the following fields when the PR arrives at the Support
Site:
>Number:
-
(ENUMERATED) The incremental identification number for this PR.
The `>Number:' field is often paired with the `>Category:'
field as
category/number
in subsequent email messages. This is for historical reasons, as well
as because Problem Reports are stored in subdirectories which are named
by category.
>State:
-
(ENUMERATED) The current state of the PR. Accepted values are:
open
-
The PR has been filed and the responsible person notified.
analyzed
-
The responsible person has analyzed the problem.
feedback
-
The problem has been solved, and the originator has been given a patch
or other fix.
closed
-
The changes have been integrated, documented, and tested, and the
originator has confirmed that the solution works.
suspended
-
Work on the problem has been postponed.
The initial state of a PR is `open'. See section 1.1 States of Problem Reports.
>Responsible:
-
(TEXT) The person responsible for this category.
>Arrival-Date:
-
(TEXT) The time that this PR was received by GNATS. The date
is provided automatically by GNATS.
>Audit-Trail:
-
(MULTITEXT) Tracks related electronic mail as well as changes in
the `>State:' and `>Responsible:' fields with the sub-fields:
State-Changed-<From>-<To>: oldstate>-<newstate
-
The old and new `>State:' field values.
Responsible-Changed-<From>-<To>: oldresp>-<newresp
-
The old and new `>Responsible:' field values.
State-Changed-By: name
-
Responsible-Changed-By: name
-
The name of the maintainer who effected the change.
State-Changed-When: timestamp
-
Responsible-Changed-When: timestamp
-
The time the change was made.
State-Changed-Why: reason...
-
Responsible-Changed-Why: reason...
-
The reason for the change.
The `>Audit-Trail:' field also contains any mail messages received
by GNATS related to this PR, in the order received.
-
>Unformatted:
(MULTITEXT) Any random text found outside the fields in the
original Problem Report.
Go to the first, previous, next, last section, table of contents.