Mercurial > hg > xemacs-beta

comparison man/gnats/fields.texi @ 112:48d667d6f17f r20-1b8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r20-1b8
author cvs
date Mon, 13 Aug 2007 09:20:48 +0200
parents
children
comparison
equal deleted inserted replaced
111:164ab62060bf 112:48d667d6f17f
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