Source

gnats / texi / fields.texi

Full commit
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
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