1. Introducing GNATS

Any support organization realizes that a large amount of data flows back and forth between the maintainers and the users of their products. This data often takes the form of problem reports and communication via electronic mail. GNATS addresses the problem of organizing this communication by defining a database made up of archived and indexed electronic mail messages.

GNATS was designed as a tool for software maintainers. It consists of several utilities which, when used in concert, formulate and administer a database of Problem Reports grouped by site-defined problem categories. It allows a support organization to keep track of problems (hence the term Problem Report) in an organized fashion. Essentially, GNATS acts as an active archive for field-separated textual data submitted through electronic mail.

1.1 The database paradigm

It is in your best interest as the maintainer of a body of work to organize the feedback you receive on that work, and to make it easy for users of your work to report problems and suggestions.

GNATS makes this easy by automatically filing incoming problem reports into appropriate places, by notifying responsible parties of the existence of the problem and (optionally) sending an acknowledgement to the submitter that the report was received, and by making these Problem Reports accessible to queries and easily editable. GNATS is a database specialized for a specific task.

GNATS was designed for use at a Support Site that handles a high level of problem-related traffic though electronic mail. It maintains Problem Reports in the form of text files with defined fields (see section GNATS data fields). The location of the database, as well as the categories it accepts as valid, the maintainers for whom it provides service, and the submitters from whom it accepts Problem Reports, are all definable by the Support Site. See section GNATS administration.

Each PR is a separate file within a main repository (see section Where GNATS lives). Editing access to the database is regulated to maintain consistency, but anyone with electronic mail access may submit Problem Reports. To make queries on the database faster, an index is kept automatically (see section The index file).

We provide several software tools so that users may submit new Problem Reports, edit existing Problem Reports, and query the database.

• send-pr is used by both product maintainers and the end users of the products they support to submit PRs to the database.

• edit-pr is used by maintainers to use when editing problem reports in the database.

• Maintainers, managers and administrators can use query-pr to make inquiries about indidvidual PRs or groups of PRs.

send-pr can also be packaged by itself and distributed to anyone you wish to receive Problem Reports from; see Configuring send-pr for the outside world.

At the Support Site, a GNATS administrator is charged with the duty of maintaining GNATS. These duties are discussed in detail in GNATS Administration, and generally include configuring GNATS for the Support Site, editing PRs that GNATS cannot process, pruning log files, setting up new problem categories, backing up the database, and distributing send-pr so that others may submit Problem Reports.

Responsibility for a given Problem Report depends on the category of the problem. Optionally, an automated reminder can be sent to the responsible person if a problem report is neglected for a requisite time period. See section Changing your local configuration.

GNATS does not have the ability to decipher random text, so any problem reports which arrive in a format GNATS does not recognize are placed in a separate directory pending investigation by the GNATS administrator (see section GNATS Administration).

Once a problem is recorded in the database, work can begin toward a solution. A problem's initial state is `open' (see section States of Problem Reports). An acknowledgement is sent to the originator of the bug report (if that feature of GNATS is activated). GNATS forwards copies of the report to the party responsible for that problem category and to the person responsible for problems arriving from that Submitter Site.

When a problem has been identified, the maintainer can change its state to `analyzed', and then to `feedback' when a solution is found. Each time the state of a PR changes, the submitter of the problem report is notified of the reason for the change. If the party responsible for the PR changes, the previous responsible party and the new responsible party receive notice of the change. The change and reason are also recorded in the `>Audit-Trail:' field of the Problem Report. (See section Editing existing Problem Reports. For information on the `>Audit-Trail:' field, see Problem Report format.)

When the originator of the Problem Report confirms that the solution works, the maintainer can change the state to closed. If the PR cannot be closed, the maintainer can change its state to suspended as a last resort. (For a more detailed description of these states, see States of Problem Reports.)

1.2 Flowchart of GNATS activities

This informal flowchart shows the relationships of the GNATS tools to each other and to the files with which they interoperate.

+===========+    +===========+    +===========+
# USER SITE #    # USER SITE #    # USER SITE #
#           #    #           #    #           #
# *send-pr* #    # *send-pr* #    # *send-pr* #
+=====|=====+    +=====|=====+    +=====|=====+
      |                V                |
      `--------->    Email....  <-------'
                ,--->     |
+===============|=========|===================+
# SUPPORT SITE  |         `---> /etc/aliases  #
#          *send-pr*                |         #
#     +-----------------------------V--------+#
#     | GNATS         GNATS_ROOT/gnats-queue/|#
#     |                             |        |#
#     |        _________            V        |#
#     |       |*file-pr*|<--- *queue-pr -r*  |#
#     |       |         |                    |#
#  _  |       |  valid  |                    |#
# |M| |       |Category?|N--.                |#
# |A| |       |_________|   |      GNATS     |#
# |I| |              Y|     |  ADMINISTRATOR |#
# |N| |               |     |                |#
# |T|<----------------|     |                |#
# |A| |               |     |  .-> *edit-pr* |#
# |I|--->*edit-pr*-.  |     V  |           | |#
# |N| |            |  |GNATS_ROOT/pending  | |#
# |E|<--*query-pr* |  |                    | |#
# |R| |       |    |  |                    | |#
# |S| |       |    V  V                    V |#
# |_| |+------------------------------------+|#
#     ||         GNATS Database             ||#
#     ||   GNATS_ROOT/CATEGORY/GNATS-ID     ||#
#     |+------------------------------------+|#
#     +--------------------------------------+#
+=============================================+

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

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.

1.4 Problem Report format

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:

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

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:

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.

Example Problem Report

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, 
duplicate, or mistaken
>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

1.4.1 Mail header fields

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.

One of the configurable options for GNATS is whether or not to retain `Received-By:' headers, which often consume a lot of space and are not often used. See section Changing your local configuration.

1.4.2 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 `config' file (see section The config file).

>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. See section The categories file, for details.

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

mistaken

No problem, user error or misunderstanding. This value is valid only at the Support Site.

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 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. This is included in the automated reply to the submitter (if that feature of GNATS is activated; see section Changing your local configuration). It is also included in the copy of the PR that is sent to the maintainer.

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 States of Problem Reports.

>Responsible:

(TEXT) The person responsible for this category. GNATS retrieves this information from the `categories' file (see section The categories file).

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

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.