Bug Maintainence with GNATS

When a maitainer recieves notification of a bug from a user, via email, the basic steps to follow are:

1. Collect all information regarding fixes to the problem or if none are available possible work arounds.
2. login to unixhub.slac.stanford.edu and invoke the program /usr/local/gnats/bin/edit-pr ( sticking /usr/local/gnats/bin in your path would be conveniant ) with the number of the problem record as an argument ( this number was specified in the email message notifying the maintainer of the problem ) The use of edit-pr is described in detail below.
3. use the information collected in step 1 to update the problem record and notify the problem submitter of the changes.

Using edit-pr to edit existing Problem Reports

edit-pr first examines the PR you wish to edit and locks it if it is not already locked. This is to prevent you from editing a PR at the same time as another user. If the PR you wish to edit is already in the process of being edited, edit-pr tells you the name of the person who owns the lock.

You may edit any field in the database that you wish. We recommend that you avoid deleting any information in the Text and MultiText fields (such as `>Description:' and `>How-To-Repeat:') . We also recommend that you record the final solution to the problem in the `>Fix:' field for future reference.

If you change the `>Responsible:' field, edit-pr prompts you to supply a reason for the change. edit-pr then mails copies of the change message to the previous responsible party, and to the new responsible party. The change is then recorded in the `>Audit-Trail:' section of the PR as follows:

Responsible-Changed-From-To: The value change, supplied

automatically by edit-pr.

Responsible-Changed-By: Your name here, supplied

automatically by edit-pr.

Responsible-Changed-When: The current date, supplied

automatically by edit-pr.

Responsible-Changed-Why: Your reason for the change; you

are prompted for this.

State-Changed-From-To: The value change, supplied

automatically by edit-pr.

State-Changed-By: Your name here, supplied

automatically by edit-pr.

State-Changed-When: The current date, supplied

automatically by edit-pr.

State-Changed-Why: Your reason for the change; you are

prompted for this.

Invoking edit-pr

edit-pr gnats-id [ -V | --version ] [ -h | --help ]

You must first determine which PR you want to edit. The options are:

-V or --version

Prints the version number edit-pr.

-h or --help

Prints the usage for edit-pr.

Edit the PR, changing any relevant fields or adding to existing information. When you exit the editor, edit-pr prompts you on standard input for a reason if you've changed either the `>Responsible:' field or the '>State:' field. edit-pr tracks the information you provide when changing either of these two fields, along with the change that occurred, your name, and the time of change in the `>Audit-Trail:' field.

Using query-pr to query the database

All arguments and options to query-pr are optional. If you do not specify a PR identification number and do not give any search parameters, query-pr displays the entire database. All arguments are considered identification numbers of Problem Reports to display. Any number of options can be given (though some make no sense when specified on the same command line); all are connected with a logical AND.

Invoking query-pr

From the Unix shell, simply type query-pr (or if you have not set your path variable /usr/local/gnats/bin/query-pr) , followed by any search parameters you wish to exercise. From Emacs type M-x query-pr. query-pr prompts you for search parameters in the minibuffer.

query-pr can also be accessed by electronic mail. To use this feature, simply send mail to the address `query-pr@unixhub.slac.stanford.edu' with command line arguments or options in the 'Subject:' line of the mail header. GNATS replies to your mail with the results of your query. The default settings for the query-pr mail server are

--restricted --state="open|analyzed|feedback|suspended"

To override the `--state' parameter, specify `--state=state' in the Subject: line of the mail header. You can not query on confidential Problem Reports by mail.

The usage for query-pr is:

query-pr [ gnats-id ]

[ -c category | --category=category ]

[ -s state | --state=state ]

[ -r responsible | --responsible=responsible ]

[ -S submitter | --submittersubmitter ]

[ -e severity | --severity=severity ]

[ -p priority | --prioritypriority} ]

[ -O originator | --originator=originator ]

[ -t text} | --text=text ]

[ -m text,/i> | --multitext=text ]

[ -R | --restricted ]

[ -F | --full ] [ -q | --summary ] [ -i | --sql ]

[ -P | --print-path ]

[ -d directory | --directorydirectory ]

[ -o outfile | --outputoutfile ]

[ -V | --version ] [ -h | --help ]

If you run query-pr from within Emacs, you can use

C-x or,/i> M-x next-error to scroll through Problem Reports one by one after the search is finished.

Search criteria

The following arguments and options specify search criteria. The lack of a criterion indicates that all values for the corresponding field are valid for the search.

Using an argument to query-pr specifies the most stringent search criteria, that of a single PR.

gnats-id

The identification number of the PR you wish to view, as shown in the `>Number:' field. Any number of gnats-id arguments may be given.

-c category

--category=category

Search only for PRs with a `>Category:' value of category. For a list of valid categories, type `send-pr -L' from the shell.

-s state

--state=state

Search only for PRs with a `>State:' value of state. state must be one of: `open', `analyzed', `feedback', `closed', or `suspended'.

-rresponsible

--responsibleresponsible

Search only for PRs with a `>Responsible:' value of responsible.

-Ssubmitter

--submittersubmitter

Search only for PRs with a `>Submitter:' value of submitter.

-e severity

--severity=severity

Search only for PRs with a `>Severity:' value of severity. severity must be one of: `critical', `serious', or 'non-critical'.

-ppriority

--priority=severitypriority

Search only for PRs with a `>Priority:' value of priority. priority must be one of: `high', `medium', or `low'.

-Ooriginator

--originator=originator

Search only for PRs with an `>Originator:' value of originator. Since this option does not reference the index, queries using it finish much faster if you also use another search criterion that is part of the index.

-t text

--text=text

Search the `Text' fields in the database for the regular expression text. Text fields include the following (the `>' and `:' Problem Report fieldname delimiters have been removed for the sake of brevity and readability):

Submitter-Id Originator Synopsis

Category Release Responsible

Arrival-Date

Queries using this option can be slow. Since this option does not reference the index, queries using it finish much faster if you also use another search criterion that is part of the index.

-m text

--multitext=text

Search the MultiText fields in the database for the regular expression text. MultiText fields include the following (again, the fieldname delimiters `>' and `:' have been omitted): Organization Environment Description

How-To-Repeat Fix Audit-Trail

Unformatted @noindent @xref{Regexps,,Querying using regular expressions}. Queries using this option can be very slow. Since this option does not reference the index, queries using it finish much faster if you also use another search criterion that @emph{is} part of the index (@pxref{index file,,The @code{index} file}). @item -R @itemx --restricted Omit from the search path PRs whose @samp{>Confidential:} fields contain the value @samp{yes}. This is equivalent to @smallexample query-pr --confidential=no @end smallexample @noindent and also disallows the use of the options @w{@samp{--outfile=@var{outfile}}} and @w{@samp{--directory=@var{directory}}}. This option is used with the @w{@code{mail-query}} tool. @item -x @itemx --skip-closed Omit closed PRs from the search path. This option is ignored if you also use @w{@samp{-s @var{state}}} or @samp{--state=@var{state}}. @end table

@subheading Output format Use the following options to select the format in which the Problem Report is printed. Use only one of these options for a given search. If you do not specify one of these options, a header@footnote{A @dfn{header} includes the mail header fields as well as the following fields: @samp{>Number:}, @samp{>Category:}, @samp{>Synopsis:}, @samp{>Confidential:}, @samp{>Severity:}, @samp{>Priority:}, @samp{>Responsible:}, @samp{>State:}, @samp{>Class:}, @samp{>Submitter-Id:}, @samp{>Originator:}, @samp{>Release:}, and @samp{>Arrival-Date:}. For suggestions on using alternate output formats in database reports, see @ref{Reporting,,Reporting}.} for the Problem Reports meeting the search criteria is printed. @table @code @item -F @itemx --full Prints all fields in the Problem Report rather than just summary information. @item -q @itemx --summary Print a short single-line summary of PR information, delimited by whitespace, including the following fields in order (the @samp{>} an @samp{:} Problem Report fieldname delimiters have been removed for the sake of brevity and readability): @smallexample Number Responsible Category State Severity Priority Submitter-Id Synopsis @end smallexample @item -i @itemx --sql Prints information on a single line with fields delimited by pipes (@samp{|}), which can be uploaded into a relational database. When you use this option, @code{query-pr} outputs @sc{Enumerated} fields numerically rather than textually; see @ref{Reporting,,Reporting on groups of Problem Reports}. @samp{query-pr -i} outputs the following fields, in order (again, the fieldname delimiters @samp{>} and @samp{:} have been omitted): @smallexample Number Category Synopsis Confidential Severity Priority Responsible State Class Submitter-Id Arrival-Date Originator Release @end smallexample When you use the @samp{-i} option, @samp{query-pr} outputs the @sc{Enumerated} fields in the database, namely @samp{>Severity:}, @samp{>Priority:}, @samp{>State:}, and @samp{>Class:}, as numbers rather than text. @xref{Reporting,,Reporting on groups of Problem Reports}, for details. @end table @subheading Other options @code{query-pr} also accepts the following options: @table @code @item -P @itemx --print-path Prints the path which @code{query-pr} used to find the current PR. A line of the form @samp{@var{directory}/@var{number}:@var{number}} is printed before each PR. This option is automatically used from within Emacs to facilitate scrolling through groups of PRs with @w{@kbd{C-x `}}. @item -d @var{directory} @itemx --directory=@var{directory} Changes the search directory to @var{directory} from @var{GNATS_ROOT}. @item -o @var{outfile} @itemx --output=@var{outfile} Prints all output to @var{outfile} rather than to the standard output. @item -V @itemx --version Prints the version number for @code{query-pr}. @item -h @itemx --help Prints the usage for @code{query-pr}. @end table @node Example queries @subsection Example queries @cindex example queries The following simple query: @smallexample query-pr --category=rats --responsible=fred --state=analyzed @end smallexample @noindent yields all PRs in the database which contain the field values: @smallexample >Category: rats @emph{and} >Responsible: fred @emph{and} >State: analyzed @end smallexample The following query: @smallexample query-pr --state="o|a" @end smallexample @noindent yields all PRs in the database whose @samp{>State:} values match either @samp{open} or @samp{analyzed} (@pxref{Regexps,,Querying using regular expressions}. This search is useful as a daily report that lists all Problem Reports which require attention. The report can be further altered using an alternate output format for @code{query-pr}; see @ref{Reporting,,Reporting on groups of Problem Reports}. A more fine-grained report may be obtained by specifying more search parameters, e.g. narrowing the search down by @w{@samp{>Submitter:}} or by @samp{>Responsible:}. The following query: @smallexample query-pr --text="The quick.*brown fox" @end smallexample @noindent yields all PRs whose @sc{Text} fields contain the text @samp{The quick} followed by @samp{brown fox} within the same field. @xref{Regexps,,Querying using regular expressions}. @node Reporting @subsection Reporting on groups of Problem Reports @cindex reporting @cindex writing reports There currently exists no separate reporting mechanism in @sc{gnats} from @code{query-pr}. However, the @samp{-q} and @samp{-i} options to @code{query-pr} allow for easy reporting. For example, a report on the current open Problem Reports in the database can be obtained using @code{awk} with @smallexample query-pr -q | awk '@{print $3 "/" $1 ": " $4@}' @end smallexample @noindent which yields a list of the form @smallexample @var{category}/@var{gnats-id}: @var{state} @emph{etc@dots{}} @end smallexample @noindent For example: @smallexample sprockets/123: open widgets/456: analyzed @emph{etc@dots{}} @end smallexample @noindent The @samp{-i} option to @code{query-pr} yields output delimited by pipes (@samp{|}). This results in the following: @smallexample @var{gnats-id}|@var{category}|@var{synopsis}|@var{confidential}|\ @var{severity}|@var{priority}|@var{responsible}|@var{state}|@var{class}|\ @var{submitter-id}|@var{arrival-date}|@var{originator}|@var{release} @end smallexample A report on Problem Reports in the database that are currently @samp{open} or @samp{analyzed} might resemble the following (the example is split into two lines in order to fit onto the page; it is intended to be typed on one command line): @smallexample query-pr -i -s "o|a" | \ awk -F\| '@{print $1 " " $2 " " $8 " " $3@}' @end smallexample @noindent which yields @smallexample @var{gnats-id} @var{category} @var{state} @var{responsible} @var{synopsis} @emph{etc@dots{}} @end smallexample @noindent For example: @smallexample 123 sprockets 1 fred The sprockets program gives bad output 456 widgets 2 barney The foo widget doesn't work with 'bar' 789 widgets 1 wilma The 'baz' widget is broken @end smallexample @noindent When you use the @samp{-i} option, @samp{query-pr} outputs the @sc{Enumerated} fields in the database, namely @samp{>Severity:}, @samp{>Priority:}, @samp{>State:}, and @samp{>Class:}, as numbers rather than text. In the example above, a @samp{>State:} value of @samp{1} means @samp{open}, @samp{2} means @samp{analyzed}, and so forth. @sc{Enumerated} fields are output according to the following paradigm: @smallexample >Severity: >Priority: critical 1 high 1 serious 2 medium 2 non-critical 3 low 3 >State: >Class: open 1 sw-bug 1 analyzed 2 doc-bug 2 suspended 3 support 3 feedback 4 change-request 4 closed 5 mistaken 5 duplicate 6 @end smallexample This makes sorting on these values easy, when combined with @code{sort}. It is left as an exercise for the reader to figure out how to do this. @ignore @c it works something like... @smallexample query-pr -i -s "o|a" | \ awk -F\| '@{print $8 "|" $1 "|" $2 "|" $3@}' | \ sort -n | \ awk -F\| '@{if $1 = "1" then \ print "Open bugs:\n" $2 " " $3 " " $3@}' \ '@{if $1 = "2" then \ print "Analyzed bugs:\n" $2 " " $3 " " $3@}' @end smallexample @end ignore @node view-pr @section Viewing individual Problem Reports @cindex @code{view-pr} in Emacs Use @code{view-pr} from within Emacs to view individual Problem Reports. Invoke @code{view-pr} with @smallexample M-x view-pr @end smallexample You are prompted to enter a Problem Report identification number (@var{gnats-id}). You can also invoke @code{view-pr} with @smallexample C-u @var{gnats-id} M-x view-pr @end smallexample @code{view-pr} allows you to view @var{gnats-id}. This is identical to using @smallexample C-u @var{gnats-id} M-x query-pr @end smallexample except that you may choose to edit the PR at any time by pressing @samp{e}.