Bug Maintainence with GNATS

This page consists primarily of instructions for the SLD maintainers describing how to query and edit records in the GNATS datadase.

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

Collect all information regarding fixes to the problem or if none are available possible work arounds.
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.
use the information collected in step 1 to update the problem record and notify the problem submitter of the changes.

Maintainers may query the Gnats database directly via WWW or they may use the program /usr/local/gnats/bin/query-pr described below to query the database and generate reports on problems in various states (e.g open, analyzed, closed etc.)

Using edit-pr to edit existing Problem Reports

Use edit-pr to make changes to existing PRs in the database. edit-pr is both a shell script and a Lisp program for gnu Emacs. Both implementations are essentially identical, though the Emacs interface provides interactive prompting for some of the fields.

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.

If you change the `>State:' field, you are prompted to supply a reason for the change. Copies of the change message are then mailed to the responsible party, and to the original submitter of the Problem Report. The change is then recorded in the `Audit-Trail' section of the PR as follows:

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.

The PR is then resubmitted to the database, and the index is updated.

IMPORTANT NOTE FOR SLD MAINTAINERS: Due to the buggy version of the Unix mail program Sendmail currently in use on the Unix mail server unixhub, you are required to DELETE THE LINE

Reply-To: Mwww@unixhub.slac.stanford.edu

from the problem record the first time you edit it. After having deleted this line, replace it with the line that occurs later in the record and looks like:

Reply-To: email_adress@some_site.some_domain.edu

where email_adress@some_site.some_domain.edu is the proper email adress of the submitter of the bug report. This will insure that the submitter is notified of any progress that is made in solving the problem. This step will hopefully be eliminated when the new version of Sendmail is installed on unixhub

Invoking edit-pr

The usage for edit-pr is:

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

To invoke edit-pr at SLAC, on a Sun use /usr/local/gnats/bin/edit-pr and on an RS/6000 use /usr/local/gnats/aix/bin/edit-pr.

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-pr calls the editor specified in your environment variable EDITOR on a temporary copy of that PR. (If you don't have the variable EDITOR defined in your environment, the default editor vi is used. To set the EDITOR environment variable from the shell issue the command: setenv EDITOR editor e.g. if you wanted to use xedit as your editor on unixhub you would issue the command setenv EDITOR /usr/local/X11R5/bin/xedit)

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

Obtain information from the database by using the program query-pr. query-pr uses search parameters you provide to find matching Problem Reports in the database. You can invoke query-pr from the Unix shell or from within Emacs. query-pr uses the same arguments whether it is invoked from the shell or from Emacs.

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.

The usage for query-pr is:

query-pr [ gnats-id ]: [ -c category | --category=category ]; [ -s state | --state=state ]; [ -r responsible | --responsible=responsible ]; [ -S submitter | --submitter=submitter ]; [ -e severity | --severity=severity ]; [ -p priority | --priority=priority} ]; [ -O originator | --originator=originator ]; [ -t text} | --text=text ]; [ -m text | --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, 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=priority: 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