[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 problem reports.
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.
1.1 The database paradigm | ||
1.2 Flowchart of GNATS activities | Flowchart of GNATS activities | |
1.3 States of Problem Reports | ||
1.4 Problem Report format |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 acknowledgment 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. 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. 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 when editing problem
reports in the database.
query-pr
to
make inquiries about individual PRs or groups of PRs.
Other interfaces to GNATS include Gnatsweb, a web-based tool which provides features for submitting and editing PRs and querying the database, and TkGnats, a Tcl/Tk-based frontend. These tools are distributed together with GNATS.
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 initially 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 Overview of GNATS configuration.
GNATS does not have the ability to decipher random text. If there is no default category set, 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 type is open (see section States of Problem Reports). An acknowledgment may be sent to the originator of the bug report (depending on whether this feature has been switched on in the GNATS configuration). 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.
When a problem has been identified, the maintainer can change its state
to analyzed, and then to feedback when a solution is found.
GNATS may be configured so that 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 the standard states, see States of Problem Reports.)
It should be emphasized that what we describe here is the default way
that GNATS works, but as of version 4, GNATS is extremely
customizable, allowing sites to tailor almost every aspect of its
behavior. See for instance The dbconfig
file and See section States of Problem Reports.)
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This informal flowchart shows the relationships of the GNATS tools to each other and to the files with which they interoperate.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Each PR goes through a defined series of states between origination and closure. By default, the originator of a PR receives notification automatically of any state changes.
Unless your site has customized states (see section The states
file),
GNATS uses these states:
The initial state of a Problem Report. This means the PR has been filed and the responsible person(s) notified.
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.
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.
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.
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.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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 eight data types as listed in Field datatypes reference. As of version 4 of GNATS all characteristics of fields, such as field name, data type, allowed values, permitted operations, on-change actions etc. are configurable.
For details, see see section The dbconfig
file.
The following is an example Problem Report with the fields that would be
present in a standard GNATS configuration. 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.
|
1.4.1 Field datatypes reference | ||
1.4.2 Mail header fields | ||
1.4.3 Problem Report fields |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following is a short reference to the characteristics of the different field types.
For details, see Field datatypes.
text
A one-line text string.
multitext
Multiple lines of text.
enum
The value in this field is required to be from a list of specified values, defined at the Support Site.
(See section The dbconfig
file, for details.
multienum
Similar to the enum
datatype, except that the field can contain
multiple values.
enumerated-in-file
Similar to enum
, but the allowed field values are listed in a
separate file on the GNATS server.
multi-enumerated-in-file
Similar to enumerated-in-file
, except that the field can contain
multiple values.
date
Used to hold dates.
integer
Used to hold integer numbers.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A Problem Report may contain any mail header field described in the
Internet standard RFC-822. The send-pr
tool can be configured
either to submit PRs to the support site by e-mail or by talking
directly to the gnatsd
network daemon on the GNATS server.
This is also true for other client tools such as Gnatsweb. Even when
these tools are set up submit PRs directly to gnatsd
, they will
still include mail header fields that identify the sender and the
subject in the submitted PR:
To:
The mail address for the Support Site, automatically supplied by the tool used to submit the PR or by the originator if plain e-mail was used.
Subject:
A terse description of the problem. This field normally contains the
same information as the Synopsis
field.
From:
Supplied automatically when PRs are submitted by plain e-mail and when
well-behaved tools such as send-pr
are used; should always
contain the originator’s e-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 The dbconfig file.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
In a standard GNATS installation, certain fields will always be
present in a Problem Report. If a PR arrives without one or more of
these fields, GNATS will add them, and if they have default
values set by the configuration at the Support Site, they will be
filled in with these values. Certain tools such as send-pr
are
set up to provide sensible defaults for most fields
(see section The send-pr.conf configuration file.)
In the list below, the field type (text
, multitext
,
enumerated
, etc.) is supplied in parantheses. The different
field types are explained briefly in Field datatypes reference.
Submitter-Id
(enumerated-in-file
) 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.
See section The submitters
file, for details.
Notify-List
(text
) Comma-separated list of e-mail-addresses of people to
notify when the PR changes significantly, i.e. when the Audit-Trail
changes. This list is independent from the Notify subfield of entries
in the ‘categories’ file of the GNATS database.
Originator
(text
) Originator’s real name. Note that the Submitter and
Originator might not be the same person/entity in all cases.
Organization
(multitext
) The originator’s organization.
Confidential
(enum
) 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.
Synopsis
(text
) One-line summary of the problem. send-pr
copies
this information to the Subject
line when you submit a Problem
Report.
Severity
(enum
) The severity of the problem. By default, 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 usually 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.
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.
Category
(enumerated-in-file
) 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-in-file
) The class of a problem in a default
GNATS installation 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 can only be set by tools at the Support Site, since it has no meaning for ordinary submitters.
See section The classes
file, for details.
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 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 he or 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 The ‘dbconfig’ file). 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 GNATS’ way of tracking followup messages that arrive by mail so that they are filed as part of the original PR.
State
(enumerated
) The current state of the PR. In default GNATS
installations, 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. Support organizations may also choose to temporarily ”park” PRs that are awaiting further input from the submitter under this state.
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 at the Support Site who is responsible for this
PR.
GNATS retrieves this information from the ‘categories’ file
(see section The categories
file).
Arrival-Date
(date
) The time that this PR was received by GNATS. The
date is provided automatically by GNATS.
Date-Required
(date
) The date by which a fix is required. This is up to the
maintainers at the Support Site to determine, so this field is not
available until after the PR has been submitted.
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. GNATS needs
to find a reference to the PR in the Subject field of received email in
order to be able to file it correctly, see Following up via direct email.
Unformatted
(multitext
) Any random text found outside the fields in the
original Problem Report.
During a Problem Report’s journey from ‘open’ to ‘closed’, two
more fields, Last-Modified
and Closed Date
(both of type
date
) will be added.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by Chad Walstrom on March 3, 2015 using texi2html 1.82.