--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/gnats/fields.texi	Mon Aug 13 09:20:48 2007 +0200
@@ -0,0 +1,520 @@
+@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).
+
+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
+
+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.
+
+@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 these 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,,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{yes}.
+
+@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,,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,,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
+