4 @section Problem Report format
5 @cindex Problem Report format
7 @cindex database similarities
10 The format of a PR is designed to reflect the nature of @sc{gnats} as a
11 database. Information is arranged into @dfn{fields}, and kept in
12 individual records (Problem Reports).
14 A Problem Report contains two different types of fields: @dfn{Mail
15 Header} fields, which are used by the mail handler for delivery, and
16 @dfn{Problem Report} fields, which contain information relevant to the
17 Problem Report and its submitter. A Problem Report is essentially a
18 specially formatted electronic mail message.
20 Problem Report fields are denoted by a keyword which begins with
21 @samp{>} and ends with @samp{:}, as in @samp{>Confidential:}. Fields
22 belong to one of three data types:
25 @cindex Problem Report data types
26 @cindex @emph{Enumerated} data types
28 One of a specific set of values, which vary according to the field. The
29 value for each keyword must be on the same line as the keyword. These
30 values are not configurable (yet).
33 For each @sc{Enumerated} keyword, the possible choices are listed in the
34 @code{send-pr} template as a comment.
36 The following fields are @sc{Enumerated} format; see the descriptions of
37 fields below for explanations of each field in detail:
41 >Confidential: >Severity: >Priority:
42 >Class: >State: >Number:
46 @cindex @emph{Text} data types
48 One single line of text which must begin and end on the same line (i.e.,
49 before a newline) as the keyword. See the descriptions of fields below
50 for explanations of each field in detail. The following fields are
55 >Submitter-Id: >Originator: >Synopsis:
56 >Category: >Release: >Responsible:
61 @cindex @emph{MultiText} data types
63 Text of any length may occur in this field. @sc{MultiText} may span
64 multiple lines and may also include blank lines. A @sc{MultiText} field
65 ends only when another keyword appears. See the descriptions of fields
66 below for explanations of each field in detail.
68 The following fields are @sc{MultiText} format:
72 >Organization: >Environment: >Description:
73 >How-To-Repeat: >Fix: >Audit-Trail:
81 @subheading Example Problem Report
84 The following is an example Problem Report. Mail headers are at the
85 top, followed by @sc{gnats} fields, which begin with @samp{>} and end
86 with @samp{:}. The @samp{Subject:} line in the mail header and the
87 @samp{>Synopsis:} field are usually duplicates of each other.
89 @cindex sample Problem Report
90 @cindex example Problem Report
91 @cindex Problem Report template
95 Message-Id: @var{message-id}
98 Reply-To: @var{address}
100 Subject: @var{subject}
102 >Number: @var{gnats-id}
103 >Category: @var{category}
104 >Synopsis: @var{synopsis}
105 >Confidential: yes @emph{or} no
106 >Severity: critical, serious, @emph{or} non-critical
107 >Priority: high, medium @emph{or} low
108 >Responsible: @var{responsible}
109 >State: open, analyzed, suspended, feedback, @emph{or} closed
110 >Class: sw-bug, doc-bug, change-request, support,
115 duplicate, @emph{or} mistaken
117 >Submitter-Id: @var{submitter-id}
118 >Arrival-Date: @var{date}
119 >Originator: @var{name}
120 >Organization: @var{organization}
121 >Release: @var{release}
131 @var{appended-messages@dots{}}
132 State-Changed-From-To: @var{from}-@var{to}
133 State-Changed-When: @var{date}
136 Responsible-Changed-From-To: @var{from}-@var{to}
137 Responsible-Changed-When: @var{date}
138 Responsible-Changed-Why:
147 * Mail header fields::
148 * Problem Report fields::
151 @c ----------------------
152 @node Mail header fields
153 @subsection Mail header fields
154 @cindex mail header fields
155 @cindex Internet standard RFC-822
157 A Problem Report may contain any mail header field described in the
158 Internet standard RFC-822. However, only the fields which identify the
159 sender and the subject are required by @code{send-pr}:
162 @cindex @code{To:} header
164 The preconfigured mail address for the Support Site where the PR is to
165 be sent, automatically supplied by @code{send-pr}.
167 @cindex @code{Subject:} header
169 A terse description of the problem. This field normally contains the
170 same information as the @samp{>Synopsis:} field.
172 @cindex @code{From:} header
174 Usually supplied automatically by the originator's mailer; should
175 contain the originator's electronic mail address.
177 @cindex @code{Reply-To:} header
179 A return address to which electronic replies can be sent; in most cases,
180 the same address as the @code{From:} field.
184 @cindex @code{Received-By:} headers
185 One of the configurable options for @sc{gnats} is whether or not to
186 retain @w{@samp{Received-By:}} headers, which often consume a lot of
187 space and are not often used. @xref{Local configuration,,Changing your
188 local configuration}.
191 @c ----------------------
192 @node Problem Report fields
193 @subsection Problem Report fields
194 @cindex GNATS database fields
197 @c FIXME - this node is loooooooooooooooong...
199 @subheading Field descriptions
201 The following fields are present whenever a PR is submitted via the
202 program @code{send-pr}. @sc{gnats} adds additional fields when the PR
203 arrives at the Support Site; explanations of them follow this list.
205 @cindex fields - list
206 @cindex GNATS fields - list
208 @cindex @code{Submitter-Id} field
209 @cindex @code{>Submitter-Id:}
211 (@sc{Text}) A unique identification code assigned by the Support Site.
212 It is used to identify all Problem Reports coming from a particular
213 site. (Submitters without a value for this field can invoke
214 @code{send-pr} with the @samp{--request-id} option to apply for one from
215 the support organization. Problem Reports from those not affiliated
216 with the support organization should use the default value of @samp{net}
219 @cindex @code{Originator} field
220 @cindex @code{>Originator:}
222 (@sc{Text}) Originator's real name. The default is the value of the
223 originator's environment variable @code{NAME}.
225 @cindex @code{>Organization:}
226 @cindex @code{Organization} field
228 (@sc{MultiText}) The originator's organization. The default value is
229 set with the variable @w{@code{DEFAULT_ORGANIZATION}} in the
231 @file{config} file (@pxref{config file,,The @code{config} file}).
234 @code{send-pr} shell script.
237 @cindex @code{Confidential} field
238 @cindex @code{>Confidential:}
239 @cindex confidentiality in PRs
240 @cindex PR confidentiality
242 (@sc{Enumerated}) Use of this field depends on the originator's
243 relationship with the support organization; contractual agreements often
244 have provisions for preserving confidentiality. Conversely, a lack of a
245 contract often means that any data provided will not be considered
246 confidential. Submitters should be advised to contact the support
247 organization directly if this is an issue.
249 If the originator's relationship to the support organization provides
250 for confidentiality, then if the value of this field is @samp{yes} the
251 support organization treats the PR as confidential; any code samples
252 provided are not made publicly available (e.g., in regression test
253 suites). The default value is @samp{no}.
255 @cindex @code{Synopsis} field
256 @cindex @code{>Synopsis:}
258 (@sc{Text}) One-line summary of the problem. @w{@code{send-pr}} copies
259 this information to the @samp{Subject:} line when you submit a Problem
262 @cindex @code{Severity} field
263 @cindex @code{>Severity:}
265 (@sc{Enumerated}) The severity of the problem. Accepted values include:
268 @cindex @emph{critical} severity problems
270 The product, component or concept is completely non-operational or some
271 essential functionality is missing. No workaround is known.
273 @cindex @emph{serious} severity problems
275 The product, component or concept is not working properly or significant
276 functionality is missing. Problems that would otherwise be considered
277 @samp{critical} are rated @samp{serious} when a workaround is known.
279 @cindex @emph{non-critical} severity problems
281 The product, component or concept is working in general, but lacks
282 features, has irritating behavior, does something wrong, or doesn't
283 match its documentation.
286 The default value is @samp{serious}.
289 @cindex @code{Priority} field
290 @cindex @code{>Priority:}
292 (@sc{Enumerated}) How soon the originator requires a solution. Accepted
296 @cindex @emph{high} priority problems
298 A solution is needed as soon as possible.
300 @cindex @emph{medium} priority problems
302 The problem should be solved in the next release.
304 @cindex @emph{low} priority problems
306 The problem should be solved in a future release.
309 The default value is @samp{medium}.
312 @cindex @code{Category} field
313 @cindex @code{>Category:}
315 (@sc{Text}) The name of the product, component or concept where
316 the problem lies. The values for this field are defined by the Support
319 @xref{categories file,,The @code{categories} file}, for details.
322 @cindex @code{Class} field
323 @cindex @code{>Class:}
325 (@sc{Enumerated}) The class of a problem can be one of the following:
328 @cindex @emph{sw-bug} class
330 A general product problem. (@samp{sw} stands for ``software''.)
332 @cindex @emph{doc-bug} class
334 A problem with the documentation.
336 @cindex @emph{change-request} class
338 A request for a change in behavior, etc.
340 @cindex @emph{support} class
342 A support problem or question.
344 @cindex @emph{duplicate} class
345 @item duplicate (@var{pr-number})
346 Duplicate PR. @var{pr-number} should be the number of the original PR.
349 @cindex @emph{mistaken} class
351 No problem, user error or misunderstanding. This value is valid only at
357 The default is @samp{sw-bug}.
360 @cindex @code{Release} field
361 @cindex @code{>Release:}
363 (@sc{Text}) Release or version number of the product, component or
366 @cindex @code{Environment} field
367 @cindex @code{>Environment:}
369 (@sc{MultiText}) Description of the environment where the problem occured:
370 machine architecture, operating system, host and target types,
371 libraries, pathnames, etc.
373 @cindex @code{Description} field
374 @cindex @code{>Description:}
376 (@sc{MultiText}) Precise description of the problem.
378 @cindex @code{How-To-Repeat} field
379 @cindex @code{>How-To-Repeat:}
380 @item >How-To-Repeat:
381 (@sc{MultiText}) Example code, input, or activities to reproduce the
382 problem. The support organization uses example code both to reproduce
383 the problem and to test whether the problem is fixed. Include all
384 preconditions, inputs, outputs, conditions after the problem, and
385 symptoms. Any additional important information should be included.
386 Include all the details that would be necessary for someone else to
387 recreate the problem reported, however obvious. Sometimes seemingly
388 arbitrary or obvious information can point the way toward a solution.
389 See also @ref{Helpful hints,,Helpful hints}.
391 @cindex @code{Fix} field
394 (@sc{MultiText}) A description of a solution to the problem, or a patch
395 which solves the problem. (This field is most often filled in at the
396 Support Site; we provide it to the submitter in case she has solved the
402 @sc{gnats} adds the following fields when the PR arrives at the Support
406 @cindex @code{Number} field
407 @cindex @code{>Number:}
409 (@sc{Enumerated}) The incremental identification number for this PR.
411 This is included in the automated reply to the submitter (if that
412 feature of @sc{gnats} is activated; @pxref{Local configuration,,Changing
413 your local configuration}). It is also included in the copy of the PR
414 that is sent to the maintainer.
417 The @samp{>Number:} field is often paired with the @samp{>Category:}
421 @var{category}/@var{number}
425 in subsequent email messages. This is for historical reasons, as well
426 as because Problem Reports are stored in subdirectories which are named
429 @cindex @code{State} field
430 @cindex @code{>State:}
432 (@sc{Enumerated}) The current state of the PR. Accepted values are:
436 The PR has been filed and the responsible person notified.
439 The responsible person has analyzed the problem.
442 The problem has been solved, and the originator has been given a patch
446 The changes have been integrated, documented, and tested, and the
447 originator has confirmed that the solution works.
450 Work on the problem has been postponed.
454 The initial state of a PR is @samp{open}. @xref{States,,States of
457 @cindex @code{Responsible} field
458 @cindex @code{>Responsible:}
460 (@sc{Text}) The person responsible for this category.
462 @sc{gnats} retrieves this information from the @file{categories} file
463 (@pxref{categories file,,The @code{categories} file}).
466 @cindex @code{>Arrival-Date:}
467 @cindex @code{Arrival-Date} field
469 (@sc{Text}) The time that this PR was received by @sc{gnats}. The date
470 is provided automatically by @sc{gnats}.
472 @cindex @code{>Audit-Trail:}
473 @cindex @code{Audit-Trail} field
475 (@sc{MultiText}) Tracks related electronic mail as well as changes in
476 the @samp{>State:} and @samp{>Responsible:} fields with the sub-fields:
479 @cindex @code{State-Changed-<From>-<To>:} in @code{>Audit-Trail:}
480 @item @w{State-Changed-<From>-<To>: @var{oldstate}>-<@var{newstate}}
481 The old and new @samp{>State:} field values.
483 @cindex @code{Responsible-Changed-<From>-<To>:} in @code{>Audit-Trail:}
484 @item @w{Responsible-Changed-<From>-<To>: @var{oldresp}>-<@var{newresp}}
485 The old and new @samp{>Responsible:} field values.
487 @cindex @code{State-Changed-By:} in @code{>Audit-Trail:}
488 @cindex @code{Responsible-Changed-By:} in @code{>Audit-Trail:}
489 @item State-Changed-By: @var{name}
490 @itemx Responsible-Changed-By: @var{name}
491 The name of the maintainer who effected the change.
493 @cindex @code{State-Changed-When:} in @code{>Audit-Trail:}
494 @cindex @code{Responsible-Changed-When:} in @code{>Audit-Trail:}
495 @item State-Changed-When: @var{timestamp}
496 @itemx Responsible-Changed-When: @var{timestamp}
497 The time the change was made.
499 @cindex @code{State-Changed-Why:} in @code{>Audit-Trail:}
500 @cindex @code{Responsible-Changed-Why:} in @code{>Audit-Trail:}
501 @item State-Changed-Why: @var{reason@dots{}}
502 @itemx Responsible-Changed-Why: @var{reason@dots{}}
503 The reason for the change.
506 @cindex subsequent mail
508 @cindex appending PRs
509 @cindex saving related mail
512 The @samp{>Audit-Trail:} field also contains any mail messages received
513 by @sc{gnats} related to this PR, in the order received.
515 @cindex @code{>Unformatted:}
516 @cindex @code{Unformatted} field
519 (@sc{MultiText}) Any random text found outside the fields in the
520 original Problem Report.