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

   1 @c $FreeBSD$
   2
   3 @node Fields
   4 @section Problem Report format
   5 @cindex Problem Report format
   6 @cindex format
   7 @cindex database similarities
   8 @cindex fields
   9
  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).
  13
  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.
  19
  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:
  23
  24 @table @asis
  25 @cindex Problem Report data types
  26 @cindex @emph{Enumerated} data types
  27 @item @sc{Enumerated}
  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).
  31
  32 @ifset SENDPR
  33 For each @sc{Enumerated} keyword, the possible choices are listed in the
  34 @code{send-pr} template as a comment.
  35 @end ifset
  36 The following fields are @sc{Enumerated} format; see the descriptions of
  37 fields below for explanations of each field in detail:
  38
  39 @smallexample
  40 @group
  41 >Confidential:   >Severity:       >Priority:
  42 >Class:          >State:          >Number:
  43 @end group
  44 @end smallexample
  45
  46 @cindex @emph{Text} data types
  47 @item @sc{Text}
  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
  51 @sc{Text} format:
  52
  53 @smallexample
  54 @group
  55 >Submitter-Id:   >Originator:     >Synopsis:
  56 >Category:       >Release:        >Responsible:
  57 >Arrival-Date:
  58 @end group
  59 @end smallexample
  60
  61 @cindex @emph{MultiText} data types
  62 @item @sc{MultiText}
  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.
  67
  68 The following fields are @sc{MultiText} format:
  69
  70 @smallexample
  71 @group
  72 >Organization:   >Environment:    >Description:
  73 >How-To-Repeat:  >Fix:            >Audit-Trail:
  74 >Unformatted:
  75 @end group
  76 @end smallexample
  77
  78 @end table
  79
  80 @ifclear SENDPR
  81 @subheading Example Problem Report
  82 @end ifclear
  83
  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.
  88
  89 @cindex sample Problem Report
  90 @cindex example Problem Report
  91 @cindex Problem Report template
  92 @cartouche
  93 @smallexample
  94 @group
  95 Message-Id:  @var{message-id}
  96 Date:        @var{date}
  97 From:        @var{address}
  98 Reply-To:    @var{address}
  99 To:          @var{bug-address}
 100 Subject:     @var{subject}
 101
 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,
 111 @ifset SENDPR
 112 @emph{or} duplicate
 113 @end ifset
 114 @ifclear SENDPR
 115 duplicate, @emph{or} mistaken
 116 @end ifclear
 117 >Submitter-Id: @var{submitter-id}
 118 >Arrival-Date: @var{date}
 119 >Originator:   @var{name}
 120 >Organization: @var{organization}
 121 >Release:      @var{release}
 122 >Environment:
 123    @var{environment}
 124 >Description:
 125    @var{description}
 126 >How-To-Repeat:
 127    @var{how-to-repeat}
 128 >Fix:
 129    @var{fix}
 130 >Audit-Trail:
 131 @var{appended-messages@dots{}}
 132 State-Changed-From-To: @var{from}-@var{to}
 133 State-Changed-When: @var{date}
 134 State-Changed-Why:
 135    @var{reason}
 136 Responsible-Changed-From-To: @var{from}-@var{to}
 137 Responsible-Changed-When: @var{date}
 138 Responsible-Changed-Why:
 139    @var{reason}
 140 >Unformatted:
 141    @var{miscellaneous}
 142 @end group
 143 @end smallexample
 144 @end cartouche
 145
 146 @menu
 147 * Mail header fields::
 148 * Problem Report fields::
 149 @end menu
 150
 151 @c ----------------------
 152 @node Mail header fields
 153 @subsection Mail header fields
 154 @cindex mail header fields
 155 @cindex Internet standard RFC-822
 156
 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}:
 160
 161 @table @code
 162 @cindex @code{To:} header
 163 @item To:
 164 The preconfigured mail address for the Support Site where the PR is to
 165 be sent, automatically supplied by @code{send-pr}.
 166
 167 @cindex @code{Subject:} header
 168 @item Subject:
 169 A terse description of the problem.  This field normally contains the
 170 same information as the @samp{>Synopsis:} field.
 171
 172 @cindex @code{From:} header
 173 @item From:
 174 Usually supplied automatically by the originator's mailer; should
 175 contain the originator's electronic mail address.
 176
 177 @cindex @code{Reply-To:} header
 178 @item Reply-To:
 179 A return address to which electronic replies can be sent; in most cases,
 180 the same address as the @code{From:} field.
 181 @end table
 182
 183 @ifclear SENDPR
 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}.
 189 @end ifclear
 190
 191 @c ----------------------
 192 @node Problem Report fields
 193 @subsection Problem Report fields
 194 @cindex GNATS database fields
 195 @cindex field format
 196
 197 @c FIXME - this node is loooooooooooooooong...
 198
 199 @subheading Field descriptions
 200
 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.
 204
 205 @cindex fields - list
 206 @cindex GNATS fields - list
 207 @table @code
 208 @cindex @code{Submitter-Id} field
 209 @cindex @code{>Submitter-Id:}
 210 @item >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}
 217 for this field.)
 218
 219 @cindex @code{Originator} field
 220 @cindex @code{>Originator:}
 221 @item >Originator:
 222 (@sc{Text}) Originator's real name.  The default is the value of the
 223 originator's environment variable @code{NAME}.
 224
 225 @cindex @code{>Organization:}
 226 @cindex @code{Organization} field
 227 @item >Organization:
 228 (@sc{MultiText}) The originator's organization.  The default value is
 229 set with the variable @w{@code{DEFAULT_ORGANIZATION}} in the
 230 @ifclear SENDPR
 231 @file{config} file (@pxref{config file,,The @code{config} file}).
 232 @end ifclear
 233 @ifset SENDPR
 234 @code{send-pr} shell script.
 235 @end ifset
 236
 237 @cindex @code{Confidential} field
 238 @cindex @code{>Confidential:}
 239 @cindex confidentiality in PRs
 240 @cindex PR confidentiality
 241 @item >Confidential:
 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.
 248
 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}.
 254
 255 @cindex @code{Synopsis} field
 256 @cindex @code{>Synopsis:}
 257 @item >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
 260 Report.
 261
 262 @cindex @code{Severity} field
 263 @cindex @code{>Severity:}
 264 @item >Severity:
 265 (@sc{Enumerated}) The severity of the problem.  Accepted values include:
 266
 267 @table @code
 268 @cindex @emph{critical} severity problems
 269 @item critical
 270 The product, component or concept is completely non-operational or some
 271 essential functionality is missing.  No workaround is known.
 272
 273 @cindex @emph{serious} severity problems
 274 @item serious
 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.
 278
 279 @cindex @emph{non-critical} severity problems
 280 @item non-critical
 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.
 284 @end table
 285 @noindent
 286 The default value is @samp{serious}.
 287 @sp 1
 288
 289 @cindex @code{Priority} field
 290 @cindex @code{>Priority:}
 291 @item >Priority:
 292 (@sc{Enumerated}) How soon the originator requires a solution.  Accepted
 293 values include:
 294
 295 @table @code
 296 @cindex @emph{high} priority problems
 297 @item high
 298 A solution is needed as soon as possible.
 299
 300 @cindex @emph{medium} priority problems
 301 @item medium
 302 The problem should be solved in the next release.
 303
 304 @cindex @emph{low} priority problems
 305 @item low
 306 The problem should be solved in a future release.
 307 @end table
 308 @noindent
 309 The default value is @samp{medium}.
 310 @sp 1
 311
 312 @cindex @code{Category} field
 313 @cindex @code{>Category:}
 314 @item >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
 317 Site.
 318 @ifclear SENDPR
 319 @xref{categories file,,The @code{categories} file}, for details.
 320 @end ifclear
 321
 322 @cindex @code{Class} field
 323 @cindex @code{>Class:}
 324 @item >Class:
 325 (@sc{Enumerated}) The class of a problem can be one of the following:
 326
 327 @table @code
 328 @cindex @emph{sw-bug} class
 329 @item sw-bug
 330 A general product problem.  (@samp{sw} stands for ``software''.)
 331
 332 @cindex @emph{doc-bug} class
 333 @item doc-bug
 334 A problem with the documentation.
 335
 336 @cindex @emph{change-request} class
 337 @item change-request
 338 A request for a change in behavior, etc.
 339
 340 @cindex @emph{support} class
 341 @item support
 342 A support problem or question.
 343
 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.
 347
 348 @ifclear SENDPR
 349 @cindex @emph{mistaken} class
 350 @item mistaken
 351 No problem, user error or misunderstanding.  This value is valid only at
 352 the Support Site.
 353 @end ifclear
 354 @end table
 355
 356 @noindent
 357 The default is @samp{sw-bug}.
 358 @sp 1
 359
 360 @cindex @code{Release} field
 361 @cindex @code{>Release:}
 362 @item >Release:
 363 (@sc{Text}) Release or version number of the product, component or
 364 concept.
 365
 366 @cindex @code{Environment} field
 367 @cindex @code{>Environment:}
 368 @item >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.
 372
 373 @cindex @code{Description} field
 374 @cindex @code{>Description:}
 375 @item >Description:
 376 (@sc{MultiText}) Precise description of the problem.
 377
 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}.
 390
 391 @cindex @code{Fix} field
 392 @cindex @code{>Fix:}
 393 @item >Fix:
 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
 397 problem.)
 398
 399 @end table
 400
 401 @noindent
 402 @sc{gnats} adds the following fields when the PR arrives at the Support
 403 Site:
 404
 405 @table @code
 406 @cindex @code{Number} field
 407 @cindex @code{>Number:}
 408 @item >Number:
 409 (@sc{Enumerated}) The incremental identification number for this PR.
 410 @ifclear SENDPR
 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.
 415 @end ifclear
 416
 417 The @samp{>Number:} field is often paired with the @samp{>Category:}
 418 field as
 419
 420 @smallexample
 421 @var{category}/@var{number}
 422 @end smallexample
 423
 424 @noindent
 425 in subsequent email messages.  This is for historical reasons, as well
 426 as because Problem Reports are stored in subdirectories which are named
 427 by category.
 428
 429 @cindex @code{State} field
 430 @cindex @code{>State:}
 431 @item >State:
 432 (@sc{Enumerated}) The current state of the PR.  Accepted values are:
 433
 434 @table @code
 435 @item open
 436 The PR has been filed and the responsible person notified.
 437
 438 @item analyzed
 439 The responsible person has analyzed the problem.
 440
 441 @item feedback
 442 The problem has been solved, and the originator has been given a patch
 443 or other fix.
 444
 445 @item closed
 446 The changes have been integrated, documented, and tested, and the
 447 originator has confirmed that the solution works.
 448
 449 @item suspended
 450 Work on the problem has been postponed.
 451 @end table
 452
 453 @noindent
 454 The initial state of a PR is @samp{open}.  @xref{States,,States of
 455 Problem Reports}.
 456
 457 @cindex @code{Responsible} field
 458 @cindex @code{>Responsible:}
 459 @item >Responsible:
 460 (@sc{Text}) The person responsible for this category.
 461 @ifclear SENDPR
 462 @sc{gnats} retrieves this information from the @file{categories} file
 463 (@pxref{categories file,,The @code{categories} file}).
 464 @end ifclear
 465
 466 @cindex @code{>Arrival-Date:}
 467 @cindex @code{Arrival-Date} field
 468 @item >Arrival-Date:
 469 (@sc{Text}) The time that this PR was received by @sc{gnats}.  The date
 470 is provided automatically by @sc{gnats}.
 471
 472 @cindex @code{>Audit-Trail:}
 473 @cindex @code{Audit-Trail} field
 474 @item >Audit-Trail:
 475 (@sc{MultiText}) Tracks related electronic mail as well as changes in
 476 the @samp{>State:} and @samp{>Responsible:} fields with the sub-fields:
 477
 478 @table @code
 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.
 482
 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.
 486
 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.
 492
 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.
 498
 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.
 504 @end table
 505
 506 @cindex subsequent mail
 507 @cindex other mail
 508 @cindex appending PRs
 509 @cindex saving related mail
 510 @cindex related mail
 511 @noindent
 512 The @samp{>Audit-Trail:} field also contains any mail messages received
 513 by @sc{gnats} related to this PR, in the order received.
 514
 515 @cindex @code{>Unformatted:}
 516 @cindex @code{Unformatted} field
 517 @item
 518  >Unformatted:
 519 (@sc{MultiText}) Any random text found outside the fields in the
 520 original Problem Report.
 521 @end table
 522