Problem Report fields
---------------------

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 these 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
     occured: 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 
See Helpful hints: 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'.  *Note States of Problem
     Reports: States.

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