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

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.

Example Problem Report

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.

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 Field datatypes reference

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.

1.4.2 Mail header fields

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.

1.4.3 Problem Report fields

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.

This document was generated by Chad Walstrom on March 3, 2015 using texi2html 1.82.