523 lines
16 KiB
Plaintext
523 lines
16 KiB
Plaintext
@c $FreeBSD$
|
|
|
|
@node Fields
|
|
@section Problem Report format
|
|
@cindex Problem Report format
|
|
@cindex format
|
|
@cindex database similarities
|
|
@cindex fields
|
|
|
|
The format of a PR is designed to reflect the nature of @sc{gnats} as a
|
|
database. Information is arranged into @dfn{fields}, and kept in
|
|
individual records (Problem Reports).
|
|
|
|
A Problem Report contains two different types of fields: @dfn{Mail
|
|
Header} fields, which are used by the mail handler for delivery, and
|
|
@dfn{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
|
|
@samp{>} and ends with @samp{:}, as in @samp{>Confidential:}. Fields
|
|
belong to one of three data types:
|
|
|
|
@table @asis
|
|
@cindex Problem Report data types
|
|
@cindex @emph{Enumerated} data types
|
|
@item @sc{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).
|
|
|
|
@ifset SENDPR
|
|
For each @sc{Enumerated} keyword, the possible choices are listed in the
|
|
@code{send-pr} template as a comment.
|
|
@end ifset
|
|
The following fields are @sc{Enumerated} format; see the descriptions of
|
|
fields below for explanations of each field in detail:
|
|
|
|
@smallexample
|
|
@group
|
|
>Confidential: >Severity: >Priority:
|
|
>Class: >State: >Number:
|
|
@end group
|
|
@end smallexample
|
|
|
|
@cindex @emph{Text} data types
|
|
@item @sc{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
|
|
@sc{Text} format:
|
|
|
|
@smallexample
|
|
@group
|
|
>Submitter-Id: >Originator: >Synopsis:
|
|
>Category: >Release: >Responsible:
|
|
>Arrival-Date:
|
|
@end group
|
|
@end smallexample
|
|
|
|
@cindex @emph{MultiText} data types
|
|
@item @sc{MultiText}
|
|
Text of any length may occur in this field. @sc{MultiText} may span
|
|
multiple lines and may also include blank lines. A @sc{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 @sc{MultiText} format:
|
|
|
|
@smallexample
|
|
@group
|
|
>Organization: >Environment: >Description:
|
|
>How-To-Repeat: >Fix: >Audit-Trail:
|
|
>Unformatted:
|
|
@end group
|
|
@end smallexample
|
|
|
|
@end table
|
|
|
|
@ifclear SENDPR
|
|
@subheading Example Problem Report
|
|
@end ifclear
|
|
|
|
The following is an example Problem Report. Mail headers are at the
|
|
top, followed by @sc{gnats} fields, which begin with @samp{>} and end
|
|
with @samp{:}. The @samp{Subject:} line in the mail header and the
|
|
@samp{>Synopsis:} field are usually duplicates of each other.
|
|
|
|
@cindex sample Problem Report
|
|
@cindex example Problem Report
|
|
@cindex Problem Report template
|
|
@cartouche
|
|
@smallexample
|
|
@group
|
|
Message-Id: @var{message-id}
|
|
Date: @var{date}
|
|
From: @var{address}
|
|
Reply-To: @var{address}
|
|
To: @var{bug-address}
|
|
Subject: @var{subject}
|
|
|
|
>Number: @var{gnats-id}
|
|
>Category: @var{category}
|
|
>Synopsis: @var{synopsis}
|
|
>Confidential: yes @emph{or} no
|
|
>Severity: critical, serious, @emph{or} non-critical
|
|
>Priority: high, medium @emph{or} low
|
|
>Responsible: @var{responsible}
|
|
>State: open, analyzed, suspended, feedback, @emph{or} closed
|
|
>Class: sw-bug, doc-bug, change-request, support,
|
|
@ifset SENDPR
|
|
@emph{or} duplicate
|
|
@end ifset
|
|
@ifclear SENDPR
|
|
duplicate, @emph{or} mistaken
|
|
@end ifclear
|
|
>Submitter-Id: @var{submitter-id}
|
|
>Arrival-Date: @var{date}
|
|
>Originator: @var{name}
|
|
>Organization: @var{organization}
|
|
>Release: @var{release}
|
|
>Environment:
|
|
@var{environment}
|
|
>Description:
|
|
@var{description}
|
|
>How-To-Repeat:
|
|
@var{how-to-repeat}
|
|
>Fix:
|
|
@var{fix}
|
|
>Audit-Trail:
|
|
@var{appended-messages@dots{}}
|
|
State-Changed-From-To: @var{from}-@var{to}
|
|
State-Changed-When: @var{date}
|
|
State-Changed-Why:
|
|
@var{reason}
|
|
Responsible-Changed-From-To: @var{from}-@var{to}
|
|
Responsible-Changed-When: @var{date}
|
|
Responsible-Changed-Why:
|
|
@var{reason}
|
|
>Unformatted:
|
|
@var{miscellaneous}
|
|
@end group
|
|
@end smallexample
|
|
@end cartouche
|
|
|
|
@menu
|
|
* Mail header fields::
|
|
* Problem Report fields::
|
|
@end menu
|
|
|
|
@c ----------------------
|
|
@node Mail header fields
|
|
@subsection Mail header fields
|
|
@cindex mail header fields
|
|
@cindex Internet standard RFC-822
|
|
|
|
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 @code{send-pr}:
|
|
|
|
@table @code
|
|
@cindex @code{To:} header
|
|
@item To:
|
|
The preconfigured mail address for the Support Site where the PR is to
|
|
be sent, automatically supplied by @code{send-pr}.
|
|
|
|
@cindex @code{Subject:} header
|
|
@item Subject:
|
|
A terse description of the problem. This field normally contains the
|
|
same information as the @samp{>Synopsis:} field.
|
|
|
|
@cindex @code{From:} header
|
|
@item From:
|
|
Usually supplied automatically by the originator's mailer; should
|
|
contain the originator's electronic mail address.
|
|
|
|
@cindex @code{Reply-To:} header
|
|
@item Reply-To:
|
|
A return address to which electronic replies can be sent; in most cases,
|
|
the same address as the @code{From:} field.
|
|
@end table
|
|
|
|
@ifclear SENDPR
|
|
@cindex @code{Received-By:} headers
|
|
One of the configurable options for @sc{gnats} is whether or not to
|
|
retain @w{@samp{Received-By:}} headers, which often consume a lot of
|
|
space and are not often used. @xref{Local configuration,,Changing your
|
|
local configuration}.
|
|
@end ifclear
|
|
|
|
@c ----------------------
|
|
@node Problem Report fields
|
|
@subsection Problem Report fields
|
|
@cindex GNATS database fields
|
|
@cindex field format
|
|
|
|
@c FIXME - this node is loooooooooooooooong...
|
|
|
|
@subheading Field descriptions
|
|
|
|
The following fields are present whenever a PR is submitted via the
|
|
program @code{send-pr}. @sc{gnats} adds additional fields when the PR
|
|
arrives at the Support Site; explanations of them follow this list.
|
|
|
|
@cindex fields - list
|
|
@cindex GNATS fields - list
|
|
@table @code
|
|
@cindex @code{Submitter-Id} field
|
|
@cindex @code{>Submitter-Id:}
|
|
@item >Submitter-Id:
|
|
(@sc{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
|
|
@code{send-pr} with the @samp{--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 @samp{net}
|
|
for this field.)
|
|
|
|
@cindex @code{Originator} field
|
|
@cindex @code{>Originator:}
|
|
@item >Originator:
|
|
(@sc{Text}) Originator's real name. The default is the value of the
|
|
originator's environment variable @code{NAME}.
|
|
|
|
@cindex @code{>Organization:}
|
|
@cindex @code{Organization} field
|
|
@item >Organization:
|
|
(@sc{MultiText}) The originator's organization. The default value is
|
|
set with the variable @w{@code{DEFAULT_ORGANIZATION}} in the
|
|
@ifclear SENDPR
|
|
@file{config} file (@pxref{config file,,The @code{config} file}).
|
|
@end ifclear
|
|
@ifset SENDPR
|
|
@code{send-pr} shell script.
|
|
@end ifset
|
|
|
|
@cindex @code{Confidential} field
|
|
@cindex @code{>Confidential:}
|
|
@cindex confidentiality in PRs
|
|
@cindex PR confidentiality
|
|
@item >Confidential:
|
|
(@sc{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 @samp{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 @samp{no}.
|
|
|
|
@cindex @code{Synopsis} field
|
|
@cindex @code{>Synopsis:}
|
|
@item >Synopsis:
|
|
(@sc{Text}) One-line summary of the problem. @w{@code{send-pr}} copies
|
|
this information to the @samp{Subject:} line when you submit a Problem
|
|
Report.
|
|
|
|
@cindex @code{Severity} field
|
|
@cindex @code{>Severity:}
|
|
@item >Severity:
|
|
(@sc{Enumerated}) The severity of the problem. Accepted values include:
|
|
|
|
@table @code
|
|
@cindex @emph{critical} severity problems
|
|
@item critical
|
|
The product, component or concept is completely non-operational or some
|
|
essential functionality is missing. No workaround is known.
|
|
|
|
@cindex @emph{serious} severity problems
|
|
@item serious
|
|
The product, component or concept is not working properly or significant
|
|
functionality is missing. Problems that would otherwise be considered
|
|
@samp{critical} are rated @samp{serious} when a workaround is known.
|
|
|
|
@cindex @emph{non-critical} severity problems
|
|
@item 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.
|
|
@end table
|
|
@noindent
|
|
The default value is @samp{serious}.
|
|
@sp 1
|
|
|
|
@cindex @code{Priority} field
|
|
@cindex @code{>Priority:}
|
|
@item >Priority:
|
|
(@sc{Enumerated}) How soon the originator requires a solution. Accepted
|
|
values include:
|
|
|
|
@table @code
|
|
@cindex @emph{high} priority problems
|
|
@item high
|
|
A solution is needed as soon as possible.
|
|
|
|
@cindex @emph{medium} priority problems
|
|
@item medium
|
|
The problem should be solved in the next release.
|
|
|
|
@cindex @emph{low} priority problems
|
|
@item low
|
|
The problem should be solved in a future release.
|
|
@end table
|
|
@noindent
|
|
The default value is @samp{medium}.
|
|
@sp 1
|
|
|
|
@cindex @code{Category} field
|
|
@cindex @code{>Category:}
|
|
@item >Category:
|
|
(@sc{Text}) The name of the product, component or concept where
|
|
the problem lies. The values for this field are defined by the Support
|
|
Site.
|
|
@ifclear SENDPR
|
|
@xref{categories file,,The @code{categories} file}, for details.
|
|
@end ifclear
|
|
|
|
@cindex @code{Class} field
|
|
@cindex @code{>Class:}
|
|
@item >Class:
|
|
(@sc{Enumerated}) The class of a problem can be one of the following:
|
|
|
|
@table @code
|
|
@cindex @emph{sw-bug} class
|
|
@item sw-bug
|
|
A general product problem. (@samp{sw} stands for ``software''.)
|
|
|
|
@cindex @emph{doc-bug} class
|
|
@item doc-bug
|
|
A problem with the documentation.
|
|
|
|
@cindex @emph{change-request} class
|
|
@item change-request
|
|
A request for a change in behavior, etc.
|
|
|
|
@cindex @emph{support} class
|
|
@item support
|
|
A support problem or question.
|
|
|
|
@cindex @emph{duplicate} class
|
|
@item duplicate (@var{pr-number})
|
|
Duplicate PR. @var{pr-number} should be the number of the original PR.
|
|
|
|
@ifclear SENDPR
|
|
@cindex @emph{mistaken} class
|
|
@item mistaken
|
|
No problem, user error or misunderstanding. This value is valid only at
|
|
the Support Site.
|
|
@end ifclear
|
|
@end table
|
|
|
|
@noindent
|
|
The default is @samp{sw-bug}.
|
|
@sp 1
|
|
|
|
@cindex @code{Release} field
|
|
@cindex @code{>Release:}
|
|
@item >Release:
|
|
(@sc{Text}) Release or version number of the product, component or
|
|
concept.
|
|
|
|
@cindex @code{Environment} field
|
|
@cindex @code{>Environment:}
|
|
@item >Environment:
|
|
(@sc{MultiText}) Description of the environment where the problem occured:
|
|
machine architecture, operating system, host and target types,
|
|
libraries, pathnames, etc.
|
|
|
|
@cindex @code{Description} field
|
|
@cindex @code{>Description:}
|
|
@item >Description:
|
|
(@sc{MultiText}) Precise description of the problem.
|
|
|
|
@cindex @code{How-To-Repeat} field
|
|
@cindex @code{>How-To-Repeat:}
|
|
@item >How-To-Repeat:
|
|
(@sc{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 @ref{Helpful hints,,Helpful hints}.
|
|
|
|
@cindex @code{Fix} field
|
|
@cindex @code{>Fix:}
|
|
@item >Fix:
|
|
(@sc{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.)
|
|
|
|
@end table
|
|
|
|
@noindent
|
|
@sc{gnats} adds the following fields when the PR arrives at the Support
|
|
Site:
|
|
|
|
@table @code
|
|
@cindex @code{Number} field
|
|
@cindex @code{>Number:}
|
|
@item >Number:
|
|
(@sc{Enumerated}) The incremental identification number for this PR.
|
|
@ifclear SENDPR
|
|
This is included in the automated reply to the submitter (if that
|
|
feature of @sc{gnats} is activated; @pxref{Local configuration,,Changing
|
|
your local configuration}). It is also included in the copy of the PR
|
|
that is sent to the maintainer.
|
|
@end ifclear
|
|
|
|
The @samp{>Number:} field is often paired with the @samp{>Category:}
|
|
field as
|
|
|
|
@smallexample
|
|
@var{category}/@var{number}
|
|
@end smallexample
|
|
|
|
@noindent
|
|
in subsequent email messages. This is for historical reasons, as well
|
|
as because Problem Reports are stored in subdirectories which are named
|
|
by category.
|
|
|
|
@cindex @code{State} field
|
|
@cindex @code{>State:}
|
|
@item >State:
|
|
(@sc{Enumerated}) The current state of the PR. Accepted values are:
|
|
|
|
@table @code
|
|
@item open
|
|
The PR has been filed and the responsible person notified.
|
|
|
|
@item analyzed
|
|
The responsible person has analyzed the problem.
|
|
|
|
@item feedback
|
|
The problem has been solved, and the originator has been given a patch
|
|
or other fix.
|
|
|
|
@item closed
|
|
The changes have been integrated, documented, and tested, and the
|
|
originator has confirmed that the solution works.
|
|
|
|
@item suspended
|
|
Work on the problem has been postponed.
|
|
@end table
|
|
|
|
@noindent
|
|
The initial state of a PR is @samp{open}. @xref{States,,States of
|
|
Problem Reports}.
|
|
|
|
@cindex @code{Responsible} field
|
|
@cindex @code{>Responsible:}
|
|
@item >Responsible:
|
|
(@sc{Text}) The person responsible for this category.
|
|
@ifclear SENDPR
|
|
@sc{gnats} retrieves this information from the @file{categories} file
|
|
(@pxref{categories file,,The @code{categories} file}).
|
|
@end ifclear
|
|
|
|
@cindex @code{>Arrival-Date:}
|
|
@cindex @code{Arrival-Date} field
|
|
@item >Arrival-Date:
|
|
(@sc{Text}) The time that this PR was received by @sc{gnats}. The date
|
|
is provided automatically by @sc{gnats}.
|
|
|
|
@cindex @code{>Audit-Trail:}
|
|
@cindex @code{Audit-Trail} field
|
|
@item >Audit-Trail:
|
|
(@sc{MultiText}) Tracks related electronic mail as well as changes in
|
|
the @samp{>State:} and @samp{>Responsible:} fields with the sub-fields:
|
|
|
|
@table @code
|
|
@cindex @code{State-Changed-<From>-<To>:} in @code{>Audit-Trail:}
|
|
@item @w{State-Changed-<From>-<To>: @var{oldstate}>-<@var{newstate}}
|
|
The old and new @samp{>State:} field values.
|
|
|
|
@cindex @code{Responsible-Changed-<From>-<To>:} in @code{>Audit-Trail:}
|
|
@item @w{Responsible-Changed-<From>-<To>: @var{oldresp}>-<@var{newresp}}
|
|
The old and new @samp{>Responsible:} field values.
|
|
|
|
@cindex @code{State-Changed-By:} in @code{>Audit-Trail:}
|
|
@cindex @code{Responsible-Changed-By:} in @code{>Audit-Trail:}
|
|
@item State-Changed-By: @var{name}
|
|
@itemx Responsible-Changed-By: @var{name}
|
|
The name of the maintainer who effected the change.
|
|
|
|
@cindex @code{State-Changed-When:} in @code{>Audit-Trail:}
|
|
@cindex @code{Responsible-Changed-When:} in @code{>Audit-Trail:}
|
|
@item State-Changed-When: @var{timestamp}
|
|
@itemx Responsible-Changed-When: @var{timestamp}
|
|
The time the change was made.
|
|
|
|
@cindex @code{State-Changed-Why:} in @code{>Audit-Trail:}
|
|
@cindex @code{Responsible-Changed-Why:} in @code{>Audit-Trail:}
|
|
@item State-Changed-Why: @var{reason@dots{}}
|
|
@itemx Responsible-Changed-Why: @var{reason@dots{}}
|
|
The reason for the change.
|
|
@end table
|
|
|
|
@cindex subsequent mail
|
|
@cindex other mail
|
|
@cindex appending PRs
|
|
@cindex saving related mail
|
|
@cindex related mail
|
|
@noindent
|
|
The @samp{>Audit-Trail:} field also contains any mail messages received
|
|
by @sc{gnats} related to this PR, in the order received.
|
|
|
|
@cindex @code{>Unformatted:}
|
|
@cindex @code{Unformatted} field
|
|
@item
|
|
>Unformatted:
|
|
(@sc{MultiText}) Any random text found outside the fields in the
|
|
original Problem Report.
|
|
@end table
|
|
|