Invoking the GNATS tools
************************

The following programs comprise GNATS:

User Utilities
--------------

These tools are used by the maintainers of a body of work (send-pr is also used by the end users of the product).

send-pr
     Used by anyone who has a problem with a body of work to submit a report of the problem to the maintainers of that work (see Submitting Problem Reports).

query-pr
     Used by software maintainers to query the GNATS database (see Querying the database).

edit-pr
     Used by software maintainers to edit Problem Reports (to record new data, to change the responsible party, etc.) (see Editing existing Problem Reports).

view-pr
     Used by software maintainers to view individual Problem Reports using Emacs (see Viewing individual Problem Reports).

Administrative Utilities
------------------------

These tools are used by the GNATS administrator; see also GNATS Administration.  For complete explanations of these utilities, see Administrative utilities.

mkcat
     Creates new categories (see Adding a problem category).

rmcat
     Removes existing categories (see Removing a problem category).

gen-index
     Generates an up-to-date copy of the index used by query-pr and edit-pr (see The index file).  Use gen-index to rebuild the index if it becomes corrupted, or if you need a copy of the current index for some reason (see Regenerating the index).

mkdist
     Creates a distribution of the program send-pr for offsite submitters of PRs (see Configuring send-pr for the outside world).

Internal Utilities
------------------

These tools are used internally by GNATS.  You should not need to run these by hand.  For complete explanations of these utilities, see Internal utilities.

queue-pr
     Handles incoming bugs, first through a mail alias by queueing incoming PRs as they arrive, and second as a periodic transfer agent between the queue and the database.

file-pr
     Files Problem Reports as they come in.

at-pr
     Sends reminders to maintainers based on quoted response times.

pr-edit
     Used by edit-pr to error-check and submit edited Problem Reports (also see Editing existing Problem Reports).

pr-addr
     Used by the edit-pr script to retrieve correct addresses from the responsible file.

See Where GNATS lives.

Submitting Problem Reports
==========================

Use send-pr to submit Problem Reports to the database. send-pr is both a shell script and a Lisp program for GNU Emacs; both implementations provide a template for submitters to complete.  In most cases, send-pr can determine intelligent default values for several fields, partially automating the bug-reporting process.

See Configuring send-pr for the outside world, for information on distributing a version of send-pr customized with your site's configuration.

     [file s-usage.texi not included]

Editing 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: (see Problem Report format).  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 (see The index file).  For information on pr-edit, the main driver for edit-pr, see Internal utilities.

Using edit-pr from within Emacs
-------------------------------

Call edit-pr from within Emacs with M-x edit-pr (If typing M-x edit-pr doesn't work, see your system administrator for help loading edit-pr into Emacs.). When edit-pr prompts you for a PR identification number, type the number of the PR you wish to edit.

If the PR is locked, Emacs announces the login name of the person who has locked the file.  If not, M-x edit-pr locks the PR, loads it into a buffer named *edit-pr*, and places the cursor in the >Number: field.  (Do not change this field.)

Edit the PR to reflect correct information.  Resubmit the PR to the database using C-c C-c (see below).

The easiest way to edit a PR from Emacs is to use the special key bindings provided.  These are:

C-c C-c
M-x gnats-submit-pr
     Saves and resubmits the PR currently being edited.  Do this when you finish editing the PR; if you simply kill the buffer, your changes are lost.

C-x C-s
M-x save-buffer
     Saves the current buffer tp a file.  You are prompted for a filename. This is not a special key binding, but at one point in the history of GNATS it was used to resubmit the PR (i.e., it was bound to M-x gnats-submit-pr).  C-x C-s now simply saves a copy of the PR.  This command does not resubmit the PR to the database.  Use C-c C-c to resubmit the PR.

C-x k
M-x gnats:kill-buffer (use this only with Emacs 18)
M-x kill-buffer
     Kills the current buffer (destroying all changes) and unlocks the current PR.  Use this to back out of a change without affecting the database.

C-c C-u
M-x unlock-pr
     Unlocks a PR that you have locked.  Use this if you have a locked PR from a failed editing session.  You are prompted for the GNATS-ID of a PR to unlock.

C-c C-q

M-x unlock-buffer
     Removes the lock on the current PR, allowing others to edit it.  The buffer remains active and non-writeable.  To relock a PR, simply type e in the buffer containing the Problem Report.

C-c C-e
M-x edit-pr
     Runs edit-pr in a new buffer.

C-c C-f
M-x change-field
     Changes the field under the cursor.  edit-pr prompts you for a new value.  If you use

          C-u C-c C-f  or
          C-u M-x change-field

     you are prompted for a field to change.

C-c C-a
M-x gnats-mail-reply
     Sends mail to the originator of this PR, using the address in the From: field of the mail header.  The Subject, To:, and Cc: fields are constructed from the Problem Report currently being edited.  Edit the message, and use C-c C-c to send it.

C-c RET
C-c C-m
M-x gnats-mail-other-window
     Splits the current window, and starts a mail message.  The Subject: field is constructed from the Problem Report currently being edited.  Edit the message, and use C-c C-c to send it.

C-c C-r
M-x gnats-responsible-change-from-to
     Changes the >Responsible: field.  edit-pr prompts you for the new responsible person, and for a message describing the reason for the change.  When you type C-c C-c to resubmit the PR, the cursor is placed in a mail buffer containing a copy of the change.  You can then edit this buffer and type C-c C-c again to send the mail.

C-c C-s
M-x gnats-state-change-from-to
     Changes the >State: field.  edit-pr prompts you for the new state, and for a message describing the reason for the change.  When you type C-c C-c to resubmit the PR, the cursor is placed in a mail buffer containing a copy of the change.  You can then edit this buffer and type C-c C-c again to send the mail.

C-c C-t
M-x category-change-from-to
     Changes the >Category: field of the PR.  edit-pr prompts you for the new category.  edit-pr also prompts you with the question

          Update the >Responsible field?

     Type y to change the value of the >Responsible: field to the name of the party responsible for the new category.  Type n to keep the current value of >Responsible:.

M-C-b
M-x gnats-backward-field
     Moves the cursor to the beginning of the value of the current field.

M-C-f
M-x gnats-forward-field
     Moves the cursor to the end of the value of the current field.

M-p
M-x gnats-previous-field
     Moves the cursor back one field to the beginning of the value of the previous field.

M-n
M-x gnats-next-field
     Moves the cursor forward one field to the beginning of the value of the next field.

Invoking edit-pr from the shell
-------------------------------

The usage for the edit-pr shell script is:

     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 for 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.)

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.

Querying 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 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 shell, simply type 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, if your version of GNATS is configured for this.  To use this feature, simply send mail to the address query-pr@YOUR-SITE 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 | --submitter=SUBMITTER ]
              [ -C [ YES | NO ] | --confidential=[ YES | NO ] ]
              [ -e SEVERITY | --severity=SEVERITY ]
              [ -p PRIORITY | --priority=PRIORITY ]
              [ -O ORIGINATOR | --originator=ORIGINATOR ]
              [ -L CLASS | --class=CLASS ]
              [ -t TEXT | --text=TEXT ]
              [ -m TEXT | --multitext=TEXT ]
              [ -R | --restricted ]
              [ -F | --full ] [ -q | --summary ] [ -i | --sql ]
              [ -P | --print-path ]
              [ -d DIRECTORY | --directory=DIRECTORY ]
              [ -o OUTFILE | --output=OUTFILE ]
              [ -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.  Regular expressions may be used as arguments to search criteria options; see Querying using regular expressions.

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.

     This field may be searched using regular expressions.  See Querying using regular expressions.  Also see Example queries.

-r RESPONSIBLE
--responsible=RESPONSIBLE
     Search only for PRs with a >Responsible: value of RESPONSIBLE.

-S SUBMITTER
--submitter=SUBMITTER
     Search only for PRs with a >Submitter: value of SUBMITTER.

-C [YES | NO]
--confidential=[YES | NO]
     Search only for PRs with a >Confidential: value of either YES or NO.  If this option is not given, all PRs are eligible for the search regardless of their confidentiality.

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

-p PRIORITY
--priority=PRIORITY
     Search only for PRs with a >Priority: value of PRIORITY. PRIORITY must be one of: high, medium, or low.

-O ORIGINATOR
--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 (see The index file).

-L CLASS
--class=CLASS
     Search only for PRs with a >Class: value of CLASS. 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 (see The index file).

-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

     See Querying using regular expressions.

     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 (see The index file).

-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

     See 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 is part of the index (see The index file).

-R
--restricted
     Omit from the search path PRs whose >Confidential: fields contain the value yes.  This is equivalent to

          query-pr --confidential=no

     and also disallows the use of the options --outfile=OUTFILE and --directory=DIRECTORY.  This option is used with the mail-query tool.

-x
--skip-closed
     Omit closed PRs from the search path.  This option is ignored if you also use -s STATE or --state=STATE.

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 (A header includes the mail header fields as well as the following fields: >Number:, >Category:, >Synopsis:, >Confidential:, >Severity:, >Priority:, >Responsible:, >State:, >Class:, >Submitter-Id:, >Originator:, >Release:, and >Arrival-Date:.  For suggestions on using alternate output formats in database reports, see Reporting.) for the Problem Reports meeting the search criteria is printed.

-F
--full
     Prints all fields in the Problem Report rather than just summary information.

-q
--summary
     Print a short single-line summary of PR information, delimited by whitespace, including the following fields in order (the > and : Problem Report fieldname delimiters have been removed for the sake of brevity and readability):

          Number         Responsible    Category
          State          Severity       Priority
          Submitter-Id   Synopsis

-i
--sql
     Prints information on a single line with fields delimited by pipes (|), which can be uploaded into a relational database.  When you use this option, query-pr outputs ENUMERATED fields numerically rather than textually; see Reporting on groups of Problem Reports.

     query-pr -i outputs the following fields, in order (again, the fieldname delimiters > and : have been omitted):

          Number         Category       Synopsis
          Confidential   Severity       Priority
          Responsible    State          Class
          Submitter-Id   Arrival-Date   Originator
          Release

     When you use the -i option, query-pr outputs the ENUMERATED fields in the database, namely >Severity:, >Priority:, >State:, and >Class:, as numbers rather than text.  See Reporting on groups of Problem Reports, for details.

Other options
-------------

query-pr also accepts the following options:

-P
--print-path
     Prints the path which query-pr used to find the current PR.  A line of the form DIRECTORY/NUMBER:NUMBER is printed before each PR.  This option is automatically used from within Emacs to facilitate scrolling through groups of PRs with C-x `.

-d DIRECTORY
--directory=DIRECTORY
     Changes the search directory to DIRECTORY from GNATS_ROOT.

-o OUTFILE
--output=OUTFILE
     Prints all output to OUTFILE rather than to the standard output.

-V
--version
     Prints the version number for query-pr.

-h
--help
     Prints the usage for query-pr.

Example queries
---------------

The following simple query:

     query-pr --category=rats --responsible=fred --state=analyzed

yields all PRs in the database which contain the field values:

     >Category:     rats         and
     >Responsible:  fred         and
     >State:        analyzed

The following query:

     query-pr --state="o|a"

yields all PRs in the database whose >State: values match either open or analyzed (see 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 query-pr; see 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 >Submitter: or by >Responsible:.

The following query:

     query-pr --text="The quick.*brown fox"

yields all PRs whose TEXT fields contain the text The quick followed by brown fox within the same field. See Querying using regular expressions.

Reporting on groups of Problem Reports
--------------------------------------

There currently exists no separate reporting mechanism in GNATS from query-pr.  However, the -q and -i options to query-pr allow for easy reporting.

For example, a report on the current open Problem Reports in the database can be obtained using awk with

     query-pr -q | awk '{print $3 "/" $1 ": " $4}'

which yields a list of the form

     CATEGORY/GNATS-ID: STATE
     etc...

For example:

     sprockets/123: open
     widgets/456: analyzed
     etc...

The -i option to query-pr yields output delimited by pipes (|).  This results in the following:

     GNATS-ID|CATEGORY|SYNOPSIS|CONFIDENTIAL|\
     SEVERITY|PRIORITY|RESPONSIBLE|STATE|CLASS|\
     SUBMITTER-ID|ARRIVAL-DATE|ORIGINATOR|RELEASE

A report on Problem Reports in the database that are currently open or 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):

     query-pr -i -s "o|a" | \
       awk -F\| '{print $1 "  " $2 "  " $8 "  " $3}'

which yields

     GNATS-ID  CATEGORY  STATE  RESPONSIBLE SYNOPSIS
     etc...

For example:

     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

When you use the -i option, query-pr outputs the ENUMERATED fields in the database, namely >Severity:, >Priority:, >State:, and >Class:, as numbers rather than text.  In the example above, a >State: value of 1 means open, 2 means analyzed, and so forth. ENUMERATED fields are output according to the following paradigm:

         >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

This makes sorting on these values easy, when combined with sort. It is left as an exercise for the reader to figure out how to do this.

Viewing individual Problem Reports
==================================

Use view-pr from within Emacs to view individual Problem Reports. Invoke view-pr with

     M-x view-pr

You are prompted to enter a Problem Report identification number (GNATS-ID).  You can also invoke view-pr with

     C-u GNATS-ID M-x view-pr

view-pr allows you to view GNATS-ID.  This is identical to using

     C-u GNATS-ID M-x query-pr

except that you may choose to edit the PR at any time by pressing e.