1@node Fields 2@section Problem Report format 3@cindex Problem Report format 4@cindex format 5@cindex database similarities 6@cindex fields 7 8The format of a PR is designed to reflect the nature of @sc{gnats} as a 9database. Information is arranged into @dfn{fields}, and kept in 10individual records (Problem Reports). 11 12Problem Report fields are denoted by a keyword which begins with 13@samp{>} and ends with @samp{:}, as in @samp{>Confidential:}. Fields 14belong 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} 20One of a specific set of values, which vary according to the field. The 21value for each keyword must be on the same line as the keyword. These 22values are not configurable (yet). 23 24@ifset SENDPR 25For each @sc{Enumerated} keyword, the possible choices are listed in the 26@code{send-pr} template as a comment. 27@end ifset 28The following fields are @sc{Enumerated} format; see the descriptions of 29fields 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} 40One single line of text which must begin and end on the same line (i.e., 41before a newline) as the keyword. See the descriptions of fields below 42for 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} 55Text of any length may occur in this field. @sc{MultiText} may span 56multiple lines and may also include blank lines. A @sc{MultiText} field 57ends only when another keyword appears. See the descriptions of fields 58below for explanations of each field in detail. 59 60The 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 72A Problem Report contains two different types of fields: @dfn{Mail 73Header} fields, which are used by the mail handler for delivery, and 74@dfn{Problem Report} fields, which contain information relevant to the 75Problem Report and its submitter. A Problem Report is essentially a 76specially formatted electronic mail message. 77 78@ifclear SENDPR 79@subheading Example Problem Report 80@end ifclear 81 82The following is an example Problem Report. Mail headers are at the 83top, followed by @sc{gnats} fields, which begin with @samp{>} and end 84with @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 93Message-Id: @var{message-id} 94Date: @var{date} 95From: @var{address} 96Reply-To: @var{address} 97To: @var{bug-address} 98Subject: @var{subject} 99 100>Number: @var{gnats-id} 101>Category: @var{category} 102>Synopsis: @var{synopsis} 103>Confidential: no @emph{or} yes 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 113duplicate, @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{}} 130State-Changed-From-To: @var{from}-@var{to} 131State-Changed-When: @var{date} 132State-Changed-Why: 133 @var{reason} 134Responsible-Changed-From-To: @var{from}-@var{to} 135Responsible-Changed-When: @var{date} 136Responsible-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 155A Problem Report may contain any mail header field described in the 156Internet standard RFC-822. However, only the fields which identify the 157sender and the subject are required by @code{send-pr}: 158 159@table @code 160@cindex @code{To:} header 161@item To: 162The preconfigured mail address for the Support Site where the PR is to 163be sent, automatically supplied by @code{send-pr}. 164 165@cindex @code{Subject:} header 166@item Subject: 167A terse description of the problem. This field normally contains the 168same information as the @samp{>Synopsis:} field. 169 170@cindex @code{From:} header 171@item From: 172Usually supplied automatically by the originator's mailer; should 173contain the originator's electronic mail address. 174 175@cindex @code{Reply-To:} header 176@item Reply-To: 177A return address to which electronic replies can be sent; in most cases, 178the same address as the @code{From:} field. 179@end table 180 181@ifclear SENDPR 182@cindex @code{Received-By:} headers 183One of the configurable options for @sc{gnats} is whether or not to 184retain @w{@samp{Received-By:}} headers, which often consume a lot of 185space and are not often used. @xref{Local configuration,,Changing your 186local 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 199The following fields are present whenever a PR is submitted via the 200program @code{send-pr}. @sc{gnats} adds additional fields when the PR 201arrives at the Support Site; explanations of these follow this list. 202 203@cindex fields - list 204@cindex GNATS fields - list 205@table @code 206@item >Submitter-Id: 207@cindex @code{Submitter-Id} field 208@cindex @code{>Submitter-Id:} 209(@sc{Text}) A unique identification code assigned by the Support Site. 210It is used to identify all Problem Reports coming from a particular 211site. (Submitters without a value for this field can invoke 212@code{send-pr} with the @samp{--request-id} option to apply for one from 213the support organization. Problem Reports from those not affiliated 214with the support organization should use the default value of @samp{net} 215for this field.) 216 217@item >Originator: 218@cindex @code{Originator} field 219@cindex @code{>Originator:} 220(@sc{Text}) Originator's real name. The default is the value of the 221originator's environment variable @code{NAME}. 222 223@item >Organization: 224@cindex @code{>Organization:} 225@cindex @code{Organization} field 226(@sc{MultiText}) The originator's organization. The default value is 227set 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@item >Confidential: 236@cindex @code{Confidential} field 237@cindex @code{>Confidential:} 238@cindex confidentiality in PRs 239@cindex PR confidentiality 240(@sc{Enumerated}) Use of this field depends on the originator's 241relationship with the support organization; contractual agreements often 242have provisions for preserving confidentiality. Conversely, a lack of a 243contract often means that any data provided will not be considered 244confidential. Submitters should be advised to contact the support 245organization directly if this is an issue. 246 247If the originator's relationship to the support organization provides 248for confidentiality, then if the value of this field is @samp{yes} the 249support organization treats the PR as confidential; any code samples 250provided are not made publicly available (e.g., in regression test 251suites). The default value is @samp{yes}. 252 253@item >Synopsis: 254@cindex @code{Synopsis} field 255@cindex @code{>Synopsis:} 256(@sc{Text}) One-line summary of the problem. @w{@code{send-pr}} copies 257this information to the @samp{Subject:} line when you submit a Problem 258Report. 259 260@item >Severity: 261@cindex @code{Severity} field 262@cindex @code{>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 268The product, component or concept is completely non-operational or some 269essential functionality is missing. No workaround is known. 270 271@cindex @emph{serious} severity problems 272@item serious 273The product, component or concept is not working properly or significant 274functionality 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 279The product, component or concept is working in general, but lacks 280features, has irritating behavior, does something wrong, or doesn't 281match its documentation. 282@end table 283@noindent 284The default value is @samp{serious}. 285@sp 1 286 287@item >Priority: 288@cindex @code{Priority} field 289@cindex @code{>Priority:} 290(@sc{Enumerated}) How soon the originator requires a solution. Accepted 291values include: 292 293@table @code 294@cindex @emph{high} priority problems 295@item high 296A solution is needed as soon as possible. 297 298@cindex @emph{medium} priority problems 299@item medium 300The problem should be solved in the next release. 301 302@cindex @emph{low} priority problems 303@item low 304The problem should be solved in a future release. 305@end table 306@noindent 307The default value is @samp{medium}. 308@sp 1 309 310@item >Category: 311@cindex @code{Category} field 312@cindex @code{>Category:} 313(@sc{Text}) The name of the product, component or concept where 314the problem lies. The values for this field are defined by the Support 315Site. 316@ifclear SENDPR 317@xref{categories,,The @code{categories} file}, for details. 318@end ifclear 319 320@item >Class: 321@cindex @code{Class} field 322@cindex @code{>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 328A general product problem. (@samp{sw} stands for ``software''.) 329 330@cindex @emph{doc-bug} class 331@item doc-bug 332A problem with the documentation. 333 334@cindex @emph{change-request} class 335@item change-request 336A request for a change in behavior, etc. 337 338@cindex @emph{support} class 339@item support 340A support problem or question. 341 342@cindex @emph{duplicate} class 343@item duplicate (@var{pr-number}) 344Duplicate PR. @var{pr-number} should be the number of the original PR. 345 346@ifclear SENDPR 347@cindex @emph{mistaken} class 348@item mistaken 349No problem, user error or misunderstanding. This value is valid only at 350the Support Site. 351@end ifclear 352@end table 353 354@noindent 355The default is @samp{sw-bug}. 356@sp 1 357 358@item >Release: 359@cindex @code{Release} field 360@cindex @code{>Release:} 361(@sc{Text}) Release or version number of the product, component or 362concept. 363 364@item >Environment: 365@cindex @code{Environment} field 366@cindex @code{>Environment:} 367(@sc{MultiText}) Description of the environment where the problem occurred: 368machine architecture, operating system, host and target types, 369libraries, pathnames, etc. 370 371@item >Description: 372@cindex @code{Description} field 373@cindex @code{>Description:} 374(@sc{MultiText}) Precise description of the problem. 375 376@item >How-To-Repeat: 377@cindex @code{How-To-Repeat} field 378@cindex @code{>How-To-Repeat:} 379(@sc{MultiText}) Example code, input, or activities to reproduce the 380problem. The support organization uses example code both to reproduce 381the problem and to test whether the problem is fixed. Include all 382preconditions, inputs, outputs, conditions after the problem, and 383symptoms. Any additional important information should be included. 384Include all the details that would be necessary for someone else to 385recreate the problem reported, however obvious. Sometimes seemingly 386arbitrary or obvious information can point the way toward a solution. 387See also @ref{Helpful hints,,Helpful hints}. 388 389@item >Fix: 390@cindex @code{Fix} field 391@cindex @code{>Fix:} 392(@sc{MultiText}) A description of a solution to the problem, or a patch 393which solves the problem. (This field is most often filled in at the 394Support Site; we provide it to the submitter in case she has solved the 395problem.) 396 397@end table 398 399@noindent 400@sc{gnats} adds the following fields when the PR arrives at the Support 401Site: 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 409This is included in the automated reply to the submitter (if that 410feature of @sc{gnats} is activated; @pxref{Local configuration,,Changing 411your local configuration}). It is also included in the copy of the PR 412that is sent to the maintainer. 413@end ifclear 414 415The @samp{>Number:} field is often paired with the @samp{>Category:} 416field as 417 418@smallexample 419@var{category}/@var{number} 420@end smallexample 421 422@noindent 423in subsequent email messages. This is for historical reasons, as well 424as because Problem Reports are stored in subdirectories which are named 425by 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 434The PR has been filed and the responsible person notified. 435 436@item analyzed 437The responsible person has analyzed the problem. 438 439@item feedback 440The problem has been solved, and the originator has been given a patch 441or other fix. 442 443@item closed 444The changes have been integrated, documented, and tested, and the 445originator has confirmed that the solution works. 446 447@item suspended 448Work on the problem has been postponed. 449@end table 450 451@noindent 452The initial state of a PR is @samp{open}. @xref{States,,States of 453Problem 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@item >Arrival-Date: 465@cindex @code{>Arrival-Date:} 466@cindex @code{Arrival-Date} field 467(@sc{Text}) The time that this PR was received by @sc{gnats}. The date 468is provided automatically by @sc{gnats}. 469 470@item >Audit-Trail: 471@cindex @code{>Audit-Trail:} 472@cindex @code{Audit-Trail} field 473(@sc{MultiText}) Tracks related electronic mail as well as changes in 474the @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}} 479The 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}} 483The 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} 489The 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} 495The 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{}} 501The reason for the change. 502@end table 503 504@noindent 505@cindex subsequent mail 506@cindex other mail 507@cindex appending PRs 508@cindex saving related mail 509@cindex related mail 510The @samp{>Audit-Trail:} field also contains any mail messages received 511by @sc{gnats} related to this PR, in the order received. 512 513@item >Unformatted: 514@cindex @code{>Unformatted:} 515@cindex @code{Unformatted} field 516(@sc{MultiText}) Any random text found outside the fields in the 517original Problem Report. 518@end table 519 520