gnu/usr.bin/send-pr/doc/fields.texi

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