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 10The format of a PR is designed to reflect the nature of @sc{gnats} as a 11database. Information is arranged into @dfn{fields}, and kept in 12individual records (Problem Reports). 13 14A Problem Report contains two different types of fields: @dfn{Mail 15Header} fields, which are used by the mail handler for delivery, and 16@dfn{Problem Report} fields, which contain information relevant to the 17Problem Report and its submitter. A Problem Report is essentially a 18specially formatted electronic mail message. 19 20Problem Report fields are denoted by a keyword which begins with 21@samp{>} and ends with @samp{:}, as in @samp{>Confidential:}. Fields 22belong 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} 28One of a specific set of values, which vary according to the field. The 29value for each keyword must be on the same line as the keyword. These 30values are not configurable (yet). 31 32@ifset SENDPR 33For each @sc{Enumerated} keyword, the possible choices are listed in the 34@code{send-pr} template as a comment. 35@end ifset 36The following fields are @sc{Enumerated} format; see the descriptions of 37fields 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} 48One single line of text which must begin and end on the same line (i.e., 49before a newline) as the keyword. See the descriptions of fields below 50for 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} 63Text of any length may occur in this field. @sc{MultiText} may span 64multiple lines and may also include blank lines. A @sc{MultiText} field 65ends only when another keyword appears. See the descriptions of fields 66below for explanations of each field in detail. 67 68The 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 84The following is an example Problem Report. Mail headers are at the 85top, followed by @sc{gnats} fields, which begin with @samp{>} and end 86with @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 95Message-Id: @var{message-id} 96Date: @var{date} 97From: @var{address} 98Reply-To: @var{address} 99To: @var{bug-address} 100Subject: @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 115duplicate, @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{}} 132State-Changed-From-To: @var{from}-@var{to} 133State-Changed-When: @var{date} 134State-Changed-Why: 135 @var{reason} 136Responsible-Changed-From-To: @var{from}-@var{to} 137Responsible-Changed-When: @var{date} 138Responsible-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 157A Problem Report may contain any mail header field described in the 158Internet standard RFC-822. However, only the fields which identify the 159sender and the subject are required by @code{send-pr}: 160 161@table @code 162@cindex @code{To:} header 163@item To: 164The preconfigured mail address for the Support Site where the PR is to 165be sent, automatically supplied by @code{send-pr}. 166 167@cindex @code{Subject:} header 168@item Subject: 169A terse description of the problem. This field normally contains the 170same information as the @samp{>Synopsis:} field. 171 172@cindex @code{From:} header 173@item From: 174Usually supplied automatically by the originator's mailer; should 175contain the originator's electronic mail address. 176 177@cindex @code{Reply-To:} header 178@item Reply-To: 179A return address to which electronic replies can be sent; in most cases, 180the same address as the @code{From:} field. 181@end table 182 183@ifclear SENDPR 184@cindex @code{Received-By:} headers 185One of the configurable options for @sc{gnats} is whether or not to 186retain @w{@samp{Received-By:}} headers, which often consume a lot of 187space and are not often used. @xref{Local configuration,,Changing your 188local 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 201The following fields are present whenever a PR is submitted via the 202program @code{send-pr}. @sc{gnats} adds additional fields when the PR 203arrives 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. 212It is used to identify all Problem Reports coming from a particular 213site. (Submitters without a value for this field can invoke 214@code{send-pr} with the @samp{--request-id} option to apply for one from 215the support organization. Problem Reports from those not affiliated 216with the support organization should use the default value of @samp{net} 217for 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 223originator'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 229set 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 243relationship with the support organization; contractual agreements often 244have provisions for preserving confidentiality. Conversely, a lack of a 245contract often means that any data provided will not be considered 246confidential. Submitters should be advised to contact the support 247organization directly if this is an issue. 248 249If the originator's relationship to the support organization provides 250for confidentiality, then if the value of this field is @samp{yes} the 251support organization treats the PR as confidential; any code samples 252provided are not made publicly available (e.g., in regression test 253suites). 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 259this information to the @samp{Subject:} line when you submit a Problem 260Report. 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 270The product, component or concept is completely non-operational or some 271essential functionality is missing. No workaround is known. 272 273@cindex @emph{serious} severity problems 274@item serious 275The product, component or concept is not working properly or significant 276functionality 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 281The product, component or concept is working in general, but lacks 282features, has irritating behavior, does something wrong, or doesn't 283match its documentation. 284@end table 285@noindent 286The 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 293values include: 294 295@table @code 296@cindex @emph{high} priority problems 297@item high 298A solution is needed as soon as possible. 299 300@cindex @emph{medium} priority problems 301@item medium 302The problem should be solved in the next release. 303 304@cindex @emph{low} priority problems 305@item low 306The problem should be solved in a future release. 307@end table 308@noindent 309The 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 316the problem lies. The values for this field are defined by the Support 317Site. 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 330A general product problem. (@samp{sw} stands for ``software''.) 331 332@cindex @emph{doc-bug} class 333@item doc-bug 334A problem with the documentation. 335 336@cindex @emph{change-request} class 337@item change-request 338A request for a change in behavior, etc. 339 340@cindex @emph{support} class 341@item support 342A support problem or question. 343 344@cindex @emph{duplicate} class 345@item duplicate (@var{pr-number}) 346Duplicate PR. @var{pr-number} should be the number of the original PR. 347 348@ifclear SENDPR 349@cindex @emph{mistaken} class 350@item mistaken 351No problem, user error or misunderstanding. This value is valid only at 352the Support Site. 353@end ifclear 354@end table 355 356@noindent 357The 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 364concept. 365 366@cindex @code{Environment} field 367@cindex @code{>Environment:} 368@item >Environment: 369(@sc{MultiText}) Description of the environment where the problem occured: 370machine architecture, operating system, host and target types, 371libraries, 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 382problem. The support organization uses example code both to reproduce 383the problem and to test whether the problem is fixed. Include all 384preconditions, inputs, outputs, conditions after the problem, and 385symptoms. Any additional important information should be included. 386Include all the details that would be necessary for someone else to 387recreate the problem reported, however obvious. Sometimes seemingly 388arbitrary or obvious information can point the way toward a solution. 389See 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 395which solves the problem. (This field is most often filled in at the 396Support Site; we provide it to the submitter in case she has solved the 397problem.) 398 399@end table 400 401@noindent 402@sc{gnats} adds the following fields when the PR arrives at the Support 403Site: 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 411This is included in the automated reply to the submitter (if that 412feature of @sc{gnats} is activated; @pxref{Local configuration,,Changing 413your local configuration}). It is also included in the copy of the PR 414that is sent to the maintainer. 415@end ifclear 416 417The @samp{>Number:} field is often paired with the @samp{>Category:} 418field as 419 420@smallexample 421@var{category}/@var{number} 422@end smallexample 423 424@noindent 425in subsequent email messages. This is for historical reasons, as well 426as because Problem Reports are stored in subdirectories which are named 427by 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 436The PR has been filed and the responsible person notified. 437 438@item analyzed 439The responsible person has analyzed the problem. 440 441@item feedback 442The problem has been solved, and the originator has been given a patch 443or other fix. 444 445@item closed 446The changes have been integrated, documented, and tested, and the 447originator has confirmed that the solution works. 448 449@item suspended 450Work on the problem has been postponed. 451@end table 452 453@noindent 454The initial state of a PR is @samp{open}. @xref{States,,States of 455Problem 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 470is 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 476the @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}} 481The 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}} 485The 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} 491The 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} 497The 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{}} 503The 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 512The @samp{>Audit-Trail:} field also contains any mail messages received 513by @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 520original Problem Report. 521@end table 522 523