diff options
Diffstat (limited to 'gnu/usr.bin/send-pr/doc/fields.texi')
| -rw-r--r-- | gnu/usr.bin/send-pr/doc/fields.texi | 522 |
1 files changed, 0 insertions, 522 deletions
diff --git a/gnu/usr.bin/send-pr/doc/fields.texi b/gnu/usr.bin/send-pr/doc/fields.texi deleted file mode 100644 index 0cce6424dc4b..000000000000 --- a/gnu/usr.bin/send-pr/doc/fields.texi +++ /dev/null @@ -1,522 +0,0 @@ -@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 - |