path: root/gnu/usr.bin/send-pr/doc/fields.texi

@c $FreeBSD: src/gnu/usr.bin/send-pr/doc/fields.texi,v 1.3.36.1.6.1 2010/12/21 17:09:25 kensmith Exp $

@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