@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 eight data types as listed in @ref{Field datatypes
reference}.  As of version 4 of @sc{gnats} all characteristics of
fields, such as field name, data type, allowed values, permitted
operations, on-change actions etc. are configurable.

@ifclear SENDPR
For details, see @pxref{dbconfig file,,The @code{dbconfig} file}.
@end ifclear
@ifclear SENDPR
@subheading Example Problem Report
@end ifclear

The following is an example Problem Report with the fields that would be
present in a standard @sc{gnats} configuration.  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
@code{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
* Field datatypes reference::
* Mail header fields::
* Problem Report fields::
@end menu

@node Field datatypes reference
@subsection Field datatypes reference

The following is a short reference to the characteristics of the
different field types.

@ifclear SENDPR
For details, see @ref{Field datatypes}.
@end ifclear

@table @code
@item text
A one-line text string.

@item multitext
Multiple lines of text.

@item enum
The value in this field is required to be from a list of specified
values, defined at the Support Site.

@ifclear SENDPR
(@xref{dbconfig file,,The @code{dbconfig} file}, for details.
@end ifclear

@item multienum
Similar to the @code{enum} datatype, except that the field can contain
multiple values.

@item enumerated-in-file
Similar to @code{enum}, but the allowed field values are listed in a
separate file on the @sc{gnats} server.

@item multi-enumerated-in-file
Similar to @code{enumerated-in-file}, except that the field can contain
multiple values.

@item date
Used to hold dates.

@item integer
Used to hold integer numbers.
@end table

@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.  The @code{send-pr} tool can be configured
either to submit PRs to the support site by e-mail or by talking
directly to the @code{gnatsd} network daemon on the @sc{gnats} server.
This is also true for other client tools such as Gnatsweb.  Even when
these tools are set up submit PRs directly to @code{gnatsd}, they will
still include mail header fields that identify the sender and the
subject in the submitted PR:

@table @code
@cindex @code{To} header
@item 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.

@cindex @code{Subject} header
@item Subject:
A terse description of the problem.  This field normally contains the
same information as the @code{Synopsis} field.

@cindex @code{From} header
@item From:
Supplied automatically when PRs are submitted by plain e-mail and when
well-behaved tools such as @code{send-pr} are used; should always
contain the originator's e-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{@code{Received-By}} headers, which often consume a lot of
space and are not often used.  @xref{dbconfig file,,The dbconfig file}.
@end ifclear

@c ----------------------
@node Problem Report fields
@subsection Problem Report fields
@cindex GNATS database fields
@cindex field format

@c FIXME - this node is loooooooooooooooong...

In a standard @sc{gnats} installation, certain fields will always be
present in a Problem Report.  If a PR arrives without one or more of
these fields, @sc{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 @code{send-pr} are
set up to provide sensible defaults for most fields
(@pxref{send-pr.conf file,,The send-pr.conf configuration file}.)

In the list below, the field type (@code{text}, @code{multitext},
@code{enumerated}, etc.) is supplied in parantheses.  The different
field types are explained briefly in @ref{Field datatypes reference}.

@cindex fields - list
@cindex GNATS fields - list
@table @code
@cindex @code{Submitter-Id} field
@item Submitter-Id
(@code{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
@code{send-pr} with the @code{--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.

@ifclear SENDPR
@xref{submitters file,,The @code{submitters} file}, for details.
@end ifclear

@cindex @code{Notify-List} field
@item Notify-List
(@code{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 @file{categories} file of the @sc{gnats} database.

@cindex @code{Originator} field
@item Originator
(@code{text}) Originator's real name.  Note that the Submitter and
Originator might not be the same person/entity in all cases.

@cindex @code{Organization} field
@item Organization
(@code{multitext}) The originator's organization.

@cindex @code{Confidential} field
@cindex confidentiality in PRs
@cindex PR confidentiality
@item Confidential
(@code{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 @samp{yes} the
support organization treats the PR as confidential; any code samples
provided are not made publicly available.

@cindex @code{Synopsis} field
@item Synopsis
(@code{text}) One-line summary of the problem.  @w{@code{send-pr}} copies
this information to the @code{Subject} line when you submit a Problem
Report.

@cindex @code{Severity} field
@item Severity
(@code{enum}) The severity of the problem.  By default, 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 usually 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

@cindex @code{Priority} field
@item Priority
(@code{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

@cindex @code{Category} field
@item Category
(@code{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.
@ifclear SENDPR
@xref{categories file,,The @code{categories} file}, for details.
@end ifclear

@cindex @code{Class} field
@item Class
(@code{enumerated-in-file}) The class of a problem in a default
@sc{gnats} installation 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 can only be set
by tools at the Support Site, since it has no meaning for ordinary
submitters.
@end ifclear
@end table

@ifclear SENDPR
@xref{classes file,,The @code{classes} file}, for details.
@end ifclear

@cindex @code{Release} field
@item Release
(@code{text}) Release or version number of the product, component or
concept.

@cindex @code{Environment} field
@item Environment
(@code{multitext}) Description of the environment where the problem
occurred: machine architecture, operating system, host and target types,
libraries, pathnames, etc.

@cindex @code{Description} field
@item Description
(@code{multitext}) Precise description of the problem.

@cindex @code{How-To-Repeat} field
@item How-To-Repeat
(@code{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
@item Fix
(@code{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.)
@end table

@noindent
@sc{gnats} adds the following fields when the PR arrives at the Support
Site:

@table @code
@cindex @code{Number} field
@item Number
(@code{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{dbconfig file,,The
@file{dbconfig} file}).  It is also included in the copy of the PR that
is sent to the maintainer.
@end ifclear

The @code{Number} field is often paired with the @code{Category} field
as

@smallexample
@var{category}/@var{number}
@end smallexample

@noindent
in subsequent email messages.  This is @sc{gnats}' way of tracking
followup messages that arrive by mail so that they are filed as part of
the original PR.

@cindex @code{State} field
@item State
(@code{enumerated}) The current state of the PR.  In default @sc{gnats}
installations, 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.  Support organizations may also choose to temporarily
''park'' PRs that are awaiting further input from the submitter under
this state.

@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
@item Responsible
(@code{text}) The person at the Support Site who is responsible for this
PR.
@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} field
@item Arrival-Date
(@code{date}) The time that this PR was received by @sc{gnats}.  The
date is provided automatically by @sc{gnats}.

@cindex @code{Date-Required}
@cindex @code{Date-Required} field
@item Date-Required
(@code{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.

@cindex @code{Audit-Trail} field
@item Audit-Trail
(@code{multitext}) Tracks related electronic mail as well as changes in
the @code{State} and @code{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 @code{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 @code{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 follow-up via email
@cindex subsequent mail
@cindex related mail
@noindent
The @code{Audit-Trail} field also contains any mail messages received by
@sc{gnats} related to this PR, in the order received.  @sc{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 @ref{follow-up via email,,
Following up via direct email}.

@cindex @code{Unformatted} field
@item Unformatted
(@code{multitext}) Any random text found outside the fields in the
original Problem Report.
@end table

During a Problem Report's journey from @samp{open} to @samp{closed}, two
more fields, @code{Last-Modified} and @code{Closed Date} (both of type
@code{date}) will be added.
