112
|
1 @node Fields
|
|
2 @section Problem Report format
|
|
3 @cindex Problem Report format
|
|
4 @cindex format
|
|
5 @cindex database similarities
|
|
6 @cindex fields
|
|
7
|
|
8 The format of a PR is designed to reflect the nature of @sc{gnats} as a
|
|
9 database. Information is arranged into @dfn{fields}, and kept in
|
|
10 individual records (Problem Reports).
|
|
11
|
|
12 Problem Report fields are denoted by a keyword which begins with
|
|
13 @samp{>} and ends with @samp{:}, as in @samp{>Confidential:}. Fields
|
|
14 belong to one of three data types:
|
|
15
|
|
16 @table @asis
|
|
17 @cindex Problem Report data types
|
|
18 @cindex @emph{Enumerated} data types
|
|
19 @item @sc{Enumerated}
|
|
20 One of a specific set of values, which vary according to the field. The
|
|
21 value for each keyword must be on the same line as the keyword. These
|
|
22 values are not configurable (yet).
|
|
23
|
|
24 @ifset SENDPR
|
|
25 For each @sc{Enumerated} keyword, the possible choices are listed in the
|
|
26 @code{send-pr} template as a comment.
|
|
27 @end ifset
|
|
28 The following fields are @sc{Enumerated} format; see the descriptions of
|
|
29 fields below for explanations of each field in detail:
|
|
30
|
|
31 @smallexample
|
|
32 @group
|
|
33 >Confidential: >Severity: >Priority:
|
|
34 >Class: >State: >Number:
|
|
35 @end group
|
|
36 @end smallexample
|
|
37
|
|
38 @cindex @emph{Text} data types
|
|
39 @item @sc{Text}
|
|
40 One single line of text which must begin and end on the same line (i.e.,
|
|
41 before a newline) as the keyword. See the descriptions of fields below
|
|
42 for explanations of each field in detail. The following fields are
|
|
43 @sc{Text} format:
|
|
44
|
|
45 @smallexample
|
|
46 @group
|
|
47 >Submitter-Id: >Originator: >Synopsis:
|
|
48 >Category: >Release: >Responsible:
|
|
49 >Arrival-Date:
|
|
50 @end group
|
|
51 @end smallexample
|
|
52
|
|
53 @cindex @emph{MultiText} data types
|
|
54 @item @sc{MultiText}
|
|
55 Text of any length may occur in this field. @sc{MultiText} may span
|
|
56 multiple lines and may also include blank lines. A @sc{MultiText} field
|
|
57 ends only when another keyword appears. See the descriptions of fields
|
|
58 below for explanations of each field in detail.
|
|
59
|
|
60 The following fields are @sc{MultiText} format:
|
|
61
|
|
62 @smallexample
|
|
63 @group
|
|
64 >Organization: >Environment: >Description:
|
|
65 >How-To-Repeat: >Fix: >Audit-Trail:
|
|
66 >Unformatted:
|
|
67 @end group
|
|
68 @end smallexample
|
|
69
|
|
70 @end table
|
|
71
|
|
72 A Problem Report contains two different types of fields: @dfn{Mail
|
|
73 Header} fields, which are used by the mail handler for delivery, and
|
|
74 @dfn{Problem Report} fields, which contain information relevant to the
|
|
75 Problem Report and its submitter. A Problem Report is essentially a
|
|
76 specially formatted electronic mail message.
|
|
77
|
|
78 @ifclear SENDPR
|
|
79 @subheading Example Problem Report
|
|
80 @end ifclear
|
|
81
|
|
82 The following is an example Problem Report. Mail headers are at the
|
|
83 top, followed by @sc{gnats} fields, which begin with @samp{>} and end
|
|
84 with @samp{:}. The @samp{Subject:} line in the mail header and the
|
|
85 @samp{>Synopsis:} field are usually duplicates of each other.
|
|
86
|
|
87 @cindex sample Problem Report
|
|
88 @cindex example Problem Report
|
|
89 @cindex Problem Report template
|
|
90 @cartouche
|
|
91 @smallexample
|
|
92 @group
|
|
93 Message-Id: @var{message-id}
|
|
94 Date: @var{date}
|
|
95 From: @var{address}
|
|
96 Reply-To: @var{address}
|
|
97 To: @var{bug-address}
|
|
98 Subject: @var{subject}
|
|
99
|
|
100 >Number: @var{gnats-id}
|
|
101 >Category: @var{category}
|
|
102 >Synopsis: @var{synopsis}
|
|
103 >Confidential: yes @emph{or} no
|
|
104 >Severity: critical, serious, @emph{or} non-critical
|
|
105 >Priority: high, medium @emph{or} low
|
|
106 >Responsible: @var{responsible}
|
|
107 >State: open, analyzed, suspended, feedback, @emph{or} closed
|
|
108 >Class: sw-bug, doc-bug, change-request, support,
|
|
109 @ifset SENDPR
|
|
110 @emph{or} duplicate
|
|
111 @end ifset
|
|
112 @ifclear SENDPR
|
|
113 duplicate, @emph{or} mistaken
|
|
114 @end ifclear
|
|
115 >Submitter-Id: @var{submitter-id}
|
|
116 >Arrival-Date: @var{date}
|
|
117 >Originator: @var{name}
|
|
118 >Organization: @var{organization}
|
|
119 >Release: @var{release}
|
|
120 >Environment:
|
|
121 @var{environment}
|
|
122 >Description:
|
|
123 @var{description}
|
|
124 >How-To-Repeat:
|
|
125 @var{how-to-repeat}
|
|
126 >Fix:
|
|
127 @var{fix}
|
|
128 >Audit-Trail:
|
|
129 @var{appended-messages@dots{}}
|
|
130 State-Changed-From-To: @var{from}-@var{to}
|
|
131 State-Changed-When: @var{date}
|
|
132 State-Changed-Why:
|
|
133 @var{reason}
|
|
134 Responsible-Changed-From-To: @var{from}-@var{to}
|
|
135 Responsible-Changed-When: @var{date}
|
|
136 Responsible-Changed-Why:
|
|
137 @var{reason}
|
|
138 >Unformatted:
|
|
139 @var{miscellaneous}
|
|
140 @end group
|
|
141 @end smallexample
|
|
142 @end cartouche
|
|
143
|
|
144 @menu
|
|
145 * Mail header fields::
|
|
146 * Problem Report fields::
|
|
147 @end menu
|
|
148
|
|
149 @c ----------------------
|
|
150 @node Mail header fields
|
|
151 @subsection Mail header fields
|
|
152 @cindex mail header fields
|
|
153 @cindex Internet standard RFC-822
|
|
154
|
|
155 A Problem Report may contain any mail header field described in the
|
|
156 Internet standard RFC-822. However, only the fields which identify the
|
|
157 sender and the subject are required by @code{send-pr}:
|
|
158
|
|
159 @table @code
|
|
160 @cindex @code{To:} header
|
|
161 @item To:
|
|
162 The preconfigured mail address for the Support Site where the PR is to
|
|
163 be sent, automatically supplied by @code{send-pr}.
|
|
164
|
|
165 @cindex @code{Subject:} header
|
|
166 @item Subject:
|
|
167 A terse description of the problem. This field normally contains the
|
|
168 same information as the @samp{>Synopsis:} field.
|
|
169
|
|
170 @cindex @code{From:} header
|
|
171 @item From:
|
|
172 Usually supplied automatically by the originator's mailer; should
|
|
173 contain the originator's electronic mail address.
|
|
174
|
|
175 @cindex @code{Reply-To:} header
|
|
176 @item Reply-To:
|
|
177 A return address to which electronic replies can be sent; in most cases,
|
|
178 the same address as the @code{From:} field.
|
|
179 @end table
|
|
180
|
|
181 @ifclear SENDPR
|
|
182 @cindex @code{Received-By:} headers
|
|
183 One of the configurable options for @sc{gnats} is whether or not to
|
|
184 retain @w{@samp{Received-By:}} headers, which often consume a lot of
|
|
185 space and are not often used. @xref{Local configuration,,Changing your
|
|
186 local configuration}.
|
|
187 @end ifclear
|
|
188
|
|
189 @c ----------------------
|
|
190 @node Problem Report fields
|
|
191 @subsection Problem Report fields
|
|
192 @cindex GNATS database fields
|
|
193 @cindex field format
|
|
194
|
|
195 @c FIXME - this node is loooooooooooooooong...
|
|
196
|
|
197 @subheading Field descriptions
|
|
198
|
|
199 The following fields are present whenever a PR is submitted via the
|
|
200 program @code{send-pr}. @sc{gnats} adds additional fields when the PR
|
|
201 arrives at the Support Site; explanations of these follow this list.
|
|
202
|
|
203 @cindex fields - list
|
|
204 @cindex GNATS fields - list
|
|
205 @table @code
|
|
206 @cindex @code{Submitter-Id} field
|
|
207 @cindex @code{>Submitter-Id:}
|
|
208 @item >Submitter-Id:
|
|
209 (@sc{Text}) A unique identification code assigned by the Support Site.
|
|
210 It is used to identify all Problem Reports coming from a particular
|
|
211 site. (Submitters without a value for this field can invoke
|
|
212 @code{send-pr} with the @samp{--request-id} option to apply for one from
|
|
213 the support organization. Problem Reports from those not affiliated
|
|
214 with the support organization should use the default value of @samp{net}
|
|
215 for this field.)
|
|
216
|
|
217 @cindex @code{Originator} field
|
|
218 @cindex @code{>Originator:}
|
|
219 @item >Originator:
|
|
220 (@sc{Text}) Originator's real name. The default is the value of the
|
|
221 originator's environment variable @code{NAME}.
|
|
222
|
|
223 @cindex @code{>Organization:}
|
|
224 @cindex @code{Organization} field
|
|
225 @item >Organization:
|
|
226 (@sc{MultiText}) The originator's organization. The default value is
|
|
227 set with the variable @w{@code{DEFAULT_ORGANIZATION}} in the
|
|
228 @ifclear SENDPR
|
|
229 @file{config} file (@pxref{config,,The @code{config} file}).
|
|
230 @end ifclear
|
|
231 @ifset SENDPR
|
|
232 @code{send-pr} shell script.
|
|
233 @end ifset
|
|
234
|
|
235 @cindex @code{Confidential} field
|
|
236 @cindex @code{>Confidential:}
|
|
237 @cindex confidentiality in PRs
|
|
238 @cindex PR confidentiality
|
|
239 @item >Confidential:
|
|
240 (@sc{Enumerated}) Use of this field depends on the originator's
|
|
241 relationship with the support organization; contractual agreements often
|
|
242 have provisions for preserving confidentiality. Conversely, a lack of a
|
|
243 contract often means that any data provided will not be considered
|
|
244 confidential. Submitters should be advised to contact the support
|
|
245 organization directly if this is an issue.
|
|
246
|
|
247 If the originator's relationship to the support organization provides
|
|
248 for confidentiality, then if the value of this field is @samp{yes} the
|
|
249 support organization treats the PR as confidential; any code samples
|
|
250 provided are not made publicly available (e.g., in regression test
|
|
251 suites). The default value is @samp{yes}.
|
|
252
|
|
253 @cindex @code{Synopsis} field
|
|
254 @cindex @code{>Synopsis:}
|
|
255 @item >Synopsis:
|
|
256 (@sc{Text}) One-line summary of the problem. @w{@code{send-pr}} copies
|
|
257 this information to the @samp{Subject:} line when you submit a Problem
|
|
258 Report.
|
|
259
|
|
260 @cindex @code{Severity} field
|
|
261 @cindex @code{>Severity:}
|
|
262 @item >Severity:
|
|
263 (@sc{Enumerated}) The severity of the problem. Accepted values include:
|
|
264
|
|
265 @table @code
|
|
266 @cindex @emph{critical} severity problems
|
|
267 @item critical
|
|
268 The product, component or concept is completely non-operational or some
|
|
269 essential functionality is missing. No workaround is known.
|
|
270
|
|
271 @cindex @emph{serious} severity problems
|
|
272 @item serious
|
|
273 The product, component or concept is not working properly or significant
|
|
274 functionality is missing. Problems that would otherwise be considered
|
|
275 @samp{critical} are rated @samp{serious} when a workaround is known.
|
|
276
|
|
277 @cindex @emph{non-critical} severity problems
|
|
278 @item non-critical
|
|
279 The product, component or concept is working in general, but lacks
|
|
280 features, has irritating behavior, does something wrong, or doesn't
|
|
281 match its documentation.
|
|
282 @end table
|
|
283 @noindent
|
|
284 The default value is @samp{serious}.
|
|
285 @sp 1
|
|
286
|
|
287 @cindex @code{Priority} field
|
|
288 @cindex @code{>Priority:}
|
|
289 @item >Priority:
|
|
290 (@sc{Enumerated}) How soon the originator requires a solution. Accepted
|
|
291 values include:
|
|
292
|
|
293 @table @code
|
|
294 @cindex @emph{high} priority problems
|
|
295 @item high
|
|
296 A solution is needed as soon as possible.
|
|
297
|
|
298 @cindex @emph{medium} priority problems
|
|
299 @item medium
|
|
300 The problem should be solved in the next release.
|
|
301
|
|
302 @cindex @emph{low} priority problems
|
|
303 @item low
|
|
304 The problem should be solved in a future release.
|
|
305 @end table
|
|
306 @noindent
|
|
307 The default value is @samp{medium}.
|
|
308 @sp 1
|
|
309
|
|
310 @cindex @code{Category} field
|
|
311 @cindex @code{>Category:}
|
|
312 @item >Category:
|
|
313 (@sc{Text}) The name of the product, component or concept where
|
|
314 the problem lies. The values for this field are defined by the Support
|
|
315 Site.
|
|
316 @ifclear SENDPR
|
|
317 @xref{categories,,The @code{categories} file}, for details.
|
|
318 @end ifclear
|
|
319
|
|
320 @cindex @code{Class} field
|
|
321 @cindex @code{>Class:}
|
|
322 @item >Class:
|
|
323 (@sc{Enumerated}) The class of a problem can be one of the following:
|
|
324
|
|
325 @table @code
|
|
326 @cindex @emph{sw-bug} class
|
|
327 @item sw-bug
|
|
328 A general product problem. (@samp{sw} stands for ``software''.)
|
|
329
|
|
330 @cindex @emph{doc-bug} class
|
|
331 @item doc-bug
|
|
332 A problem with the documentation.
|
|
333
|
|
334 @cindex @emph{change-request} class
|
|
335 @item change-request
|
|
336 A request for a change in behavior, etc.
|
|
337
|
|
338 @cindex @emph{support} class
|
|
339 @item support
|
|
340 A support problem or question.
|
|
341
|
|
342 @cindex @emph{duplicate} class
|
|
343 @item duplicate (@var{pr-number})
|
|
344 Duplicate PR. @var{pr-number} should be the number of the original PR.
|
|
345
|
|
346 @ifclear SENDPR
|
|
347 @cindex @emph{mistaken} class
|
|
348 @item mistaken
|
|
349 No problem, user error or misunderstanding. This value is valid only at
|
|
350 the Support Site.
|
|
351 @end ifclear
|
|
352 @end table
|
|
353
|
|
354 @noindent
|
|
355 The default is @samp{sw-bug}.
|
|
356 @sp 1
|
|
357
|
|
358 @cindex @code{Release} field
|
|
359 @cindex @code{>Release:}
|
|
360 @item >Release:
|
|
361 (@sc{Text}) Release or version number of the product, component or
|
|
362 concept.
|
|
363
|
|
364 @cindex @code{Environment} field
|
|
365 @cindex @code{>Environment:}
|
|
366 @item >Environment:
|
|
367 (@sc{MultiText}) Description of the environment where the problem occured:
|
|
368 machine architecture, operating system, host and target types,
|
|
369 libraries, pathnames, etc.
|
|
370
|
|
371 @cindex @code{Description} field
|
|
372 @cindex @code{>Description:}
|
|
373 @item >Description:
|
|
374 (@sc{MultiText}) Precise description of the problem.
|
|
375
|
|
376 @cindex @code{How-To-Repeat} field
|
|
377 @cindex @code{>How-To-Repeat:}
|
|
378 @item >How-To-Repeat:
|
|
379 (@sc{MultiText}) Example code, input, or activities to reproduce the
|
|
380 problem. The support organization uses example code both to reproduce
|
|
381 the problem and to test whether the problem is fixed. Include all
|
|
382 preconditions, inputs, outputs, conditions after the problem, and
|
|
383 symptoms. Any additional important information should be included.
|
|
384 Include all the details that would be necessary for someone else to
|
|
385 recreate the problem reported, however obvious. Sometimes seemingly
|
|
386 arbitrary or obvious information can point the way toward a solution.
|
|
387 See also @ref{Helpful hints,,Helpful hints}.
|
|
388
|
|
389 @cindex @code{Fix} field
|
|
390 @cindex @code{>Fix:}
|
|
391 @item >Fix:
|
|
392 (@sc{MultiText}) A description of a solution to the problem, or a patch
|
|
393 which solves the problem. (This field is most often filled in at the
|
|
394 Support Site; we provide it to the submitter in case she has solved the
|
|
395 problem.)
|
|
396
|
|
397 @end table
|
|
398
|
|
399 @noindent
|
|
400 @sc{gnats} adds the following fields when the PR arrives at the Support
|
|
401 Site:
|
|
402
|
|
403 @table @code
|
|
404 @cindex @code{Number} field
|
|
405 @cindex @code{>Number:}
|
|
406 @item >Number:
|
|
407 (@sc{Enumerated}) The incremental identification number for this PR.
|
|
408 @ifclear SENDPR
|
|
409 This is included in the automated reply to the submitter (if that
|
|
410 feature of @sc{gnats} is activated; @pxref{Local configuration,,Changing
|
|
411 your local configuration}). It is also included in the copy of the PR
|
|
412 that is sent to the maintainer.
|
|
413 @end ifclear
|
|
414
|
|
415 The @samp{>Number:} field is often paired with the @samp{>Category:}
|
|
416 field as
|
|
417
|
|
418 @smallexample
|
|
419 @var{category}/@var{number}
|
|
420 @end smallexample
|
|
421
|
|
422 @noindent
|
|
423 in subsequent email messages. This is for historical reasons, as well
|
|
424 as because Problem Reports are stored in subdirectories which are named
|
|
425 by category.
|
|
426
|
|
427 @cindex @code{State} field
|
|
428 @cindex @code{>State:}
|
|
429 @item >State:
|
|
430 (@sc{Enumerated}) The current state of the PR. Accepted values are:
|
|
431
|
|
432 @table @code
|
|
433 @item open
|
|
434 The PR has been filed and the responsible person notified.
|
|
435
|
|
436 @item analyzed
|
|
437 The responsible person has analyzed the problem.
|
|
438
|
|
439 @item feedback
|
|
440 The problem has been solved, and the originator has been given a patch
|
|
441 or other fix.
|
|
442
|
|
443 @item closed
|
|
444 The changes have been integrated, documented, and tested, and the
|
|
445 originator has confirmed that the solution works.
|
|
446
|
|
447 @item suspended
|
|
448 Work on the problem has been postponed.
|
|
449 @end table
|
|
450
|
|
451 @noindent
|
|
452 The initial state of a PR is @samp{open}. @xref{States,,States of
|
|
453 Problem Reports}.
|
|
454
|
|
455 @cindex @code{Responsible} field
|
|
456 @cindex @code{>Responsible:}
|
|
457 @item >Responsible:
|
|
458 (@sc{Text}) The person responsible for this category.
|
|
459 @ifclear SENDPR
|
|
460 @sc{gnats} retrieves this information from the @file{categories} file
|
|
461 (@pxref{categories,,The @code{categories} file}).
|
|
462 @end ifclear
|
|
463
|
|
464 @cindex @code{>Arrival-Date:}
|
|
465 @cindex @code{Arrival-Date} field
|
|
466 @item >Arrival-Date:
|
|
467 (@sc{Text}) The time that this PR was received by @sc{gnats}. The date
|
|
468 is provided automatically by @sc{gnats}.
|
|
469
|
|
470 @cindex @code{>Audit-Trail:}
|
|
471 @cindex @code{Audit-Trail} field
|
|
472 @item >Audit-Trail:
|
|
473 (@sc{MultiText}) Tracks related electronic mail as well as changes in
|
|
474 the @samp{>State:} and @samp{>Responsible:} fields with the sub-fields:
|
|
475
|
|
476 @table @code
|
|
477 @cindex @code{State-Changed-<From>-<To>:} in @code{>Audit-Trail:}
|
|
478 @item @w{State-Changed-<From>-<To>: @var{oldstate}>-<@var{newstate}}
|
|
479 The old and new @samp{>State:} field values.
|
|
480
|
|
481 @cindex @code{Responsible-Changed-<From>-<To>:} in @code{>Audit-Trail:}
|
|
482 @item @w{Responsible-Changed-<From>-<To>: @var{oldresp}>-<@var{newresp}}
|
|
483 The old and new @samp{>Responsible:} field values.
|
|
484
|
|
485 @cindex @code{State-Changed-By:} in @code{>Audit-Trail:}
|
|
486 @cindex @code{Responsible-Changed-By:} in @code{>Audit-Trail:}
|
|
487 @item State-Changed-By: @var{name}
|
|
488 @itemx Responsible-Changed-By: @var{name}
|
|
489 The name of the maintainer who effected the change.
|
|
490
|
|
491 @cindex @code{State-Changed-When:} in @code{>Audit-Trail:}
|
|
492 @cindex @code{Responsible-Changed-When:} in @code{>Audit-Trail:}
|
|
493 @item State-Changed-When: @var{timestamp}
|
|
494 @itemx Responsible-Changed-When: @var{timestamp}
|
|
495 The time the change was made.
|
|
496
|
|
497 @cindex @code{State-Changed-Why:} in @code{>Audit-Trail:}
|
|
498 @cindex @code{Responsible-Changed-Why:} in @code{>Audit-Trail:}
|
|
499 @item State-Changed-Why: @var{reason@dots{}}
|
|
500 @itemx Responsible-Changed-Why: @var{reason@dots{}}
|
|
501 The reason for the change.
|
|
502 @end table
|
|
503
|
|
504 @cindex subsequent mail
|
|
505 @cindex other mail
|
|
506 @cindex appending PRs
|
|
507 @cindex saving related mail
|
|
508 @cindex related mail
|
|
509 @noindent
|
|
510 The @samp{>Audit-Trail:} field also contains any mail messages received
|
|
511 by @sc{gnats} related to this PR, in the order received.
|
|
512
|
|
513 @cindex @code{>Unformatted:}
|
|
514 @cindex @code{Unformatted} field
|
|
515 @item
|
|
516 >Unformatted:
|
|
517 (@sc{MultiText}) Any random text found outside the fields in the
|
|
518 original Problem Report.
|
|
519 @end table
|
|
520
|