     [file version.texi not included]

     START-INFO-DIR-ENTRY
     * Keeping Track: (gnats).        GNU Problem Report Management System
     END-INFO-DIR-ENTRY

Copyright © 1993, 1995 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.

Overview
********

This manual documents GNATS, the GNU Problem Report Management System, version VERSION.  GNATS is a bug-tracking tool designed for use at a central Support Site.  Users who experience problems use electronic mail to communicate these problems to maintainers at that Support Site.  GNATS partially automates the tracking of these Problem Reports (PRs) by:

  * organizing problem reports into a database and notifying responsible parties of suspected bugs;

  * allowing support personnel and their managers to edit and query accumulated bugs; and

  * providing a reliable archive of problems (and their subsequent solutions) with a given program.

GNATS offers many of the same features offered by more generalized databases, including editing, querying, and basic reporting.  The GNATS database itself is an ordered repository for problem reports; each PR receives a unique, incremental PR number which identifies it throughout its lifetime.  For a discussion on the working system adopted by GNATS, see The database paradigm.

You can access the submitting, editing, and querying functions of GNATS from within GNU Emacs.  See Invoking the GNATS tools.

Introducing GNATS
*****************

Any support organization realizes that a large amount of data flows back and forth between the maintainers and the users of their products.  This data often takes the form of problem reports and communication via electronic mail.  GNATS addresses the problem of organizing this communication by defining a database made up of archived and indexed electronic mail messages.

GNATS was designed as a tool for software maintainers.  It consists of several utilities which, when used in concert, formulate and administer a database of Problem Reports grouped by site-defined problem categories.  It allows a support organization to keep track of problems (hence the term Problem Report) in an organized fashion.  Essentially, GNATS acts as an active archive for field-separated textual data submitted through electronic mail.

The database paradigm
=====================

It is in your best interest as the maintainer of a body of work to organize the feedback you receive on that work, and to make it easy for users of your work to report problems and suggestions.

GNATS makes this easy by automatically filing incoming problem reports into appropriate places, by notifying responsible parties of the existence of the problem and (optionally) sending an acknowledgement to the submitter that the report was received, and by making these Problem Reports accessible to queries and easily editable.  GNATS is a database specialized for a specific task.

GNATS was designed for use at a Support Site that handles a high level of problem-related traffic though electronic mail.  It maintains Problem Reports in the form of text files with defined fields (see GNATS data fields).  The location of the database, as well as the categories it accepts as valid, the maintainers for whom it provides service, and the submitters from whom it accepts Problem Reports, are all definable by the Support Site. See GNATS administration.

Each PR is a separate file within a main repository (see Where GNATS lives).  Editing access to the database is regulated to maintain consistency, but anyone with electronic mail access may submit Problem Reports.  To make queries on the database faster, an index is kept automatically (see The index file).

We provide several software tools so that users may submit new Problem Reports, edit existing Problem Reports, and query the database.

  * send-pr is used by both product maintainers and the end users of the products they support to submit PRs to the database.

  * edit-pr is used by maintainers to use when editing problem reports in the database.

  * Maintainers, managers and administrators can use query-pr to make inquiries about indidvidual PRs or groups of PRs.

send-pr can also be packaged by itself and distributed to anyone you wish to receive Problem  Reports  from; see Configuring send-pr for the outside world.

At the Support Site, a GNATS administrator is charged with the duty of maintaining GNATS.  These duties are discussed in detail in GNATS Administration, and generally include configuring GNATS for the Support Site, editing PRs that GNATS cannot process, pruning log files, setting up new problem categories, backing up the database, and distributing send-pr so that others may submit Problem Reports.

Responsibility for a given Problem Report depends on the category of the problem.  Optionally, an automated reminder can be sent to the responsible person if a problem report is neglected for a requisite time period.  See Changing your local configuration.

GNATS does not have the ability to decipher random text, so any problem reports which arrive in a format GNATS does not recognize are placed in a separate directory pending investigation by the GNATS administrator (see GNATS Administration).

Once a problem is recorded in the database, work can begin toward a solution.  A problem's initial state is open (see States of Problem Reports).  An acknowledgement is sent to the originator of the bug report (if that feature of GNATS is activated).  GNATS forwards copies of the report to the party responsible for that problem category and to the person responsible for problems arriving from that Submitter Site.

When a problem has been identified, the maintainer can change its state to analyzed, and then to feedback when a solution is found.  Each time the state of a PR changes, the submitter of the problem report is notified of the reason for the change.  If the party responsible for the PR changes, the previous responsible party and the new responsible party receive notice of the change.  The change and reason are also recorded in the >Audit-Trail: field of the Problem Report.  (see Editing existing Problem Reports.  For information on the >Audit-Trail: field, see Problem Report format.)

When the originator of the Problem Report confirms that the solution works, the maintainer can change the state to closed.  If the PR cannot be closed, the maintainer can change its state to suspended as a last resort.  (For a more detailed description of these states, see States of Problem Reports.)

Flowchart of GNATS activities
=============================

This informal flowchart shows the relationships of the GNATS tools to each other and to the files with which they interoperate.

          [file flowchart.txt not included]

     [file states.texi not included]

     [file fields.texi not included]

     [file p-usage.texi not included]

     [file p-admin.texi not included]

Installing GNATS
****************

     [file p-inst.texi not included]

Where GNATS lives
*****************

We use a few conventions when referring to the installation structure GNATS uses.  These values are adjustable when you build and install GNATS (see Installing GNATS).

PREFIX
======

PREFIX corresponds to the variable prefix for configure, which passes it on to the Makefile it creates. PREFIX sets the root installation directory for host-independent files as follows:

libraries
     PREFIX/lib

man pages
     PREFIX/man

info documents
     PREFIX/info

include files
     PREFIX/include

etc...

The default value for PREFIX is /usr/local, which can be changed on the command line to configure using

     configure --prefix=PREFIX ...

See Configuring and compiling the software.

EXEC-PREFIX
===========

EXEC-PREFIX corresponds to the variable exec_prefix for configure, which passes it on to the Makefile it creates. EXEC-PREFIX sets the root installation for host-dependent files as follows:

binary tools
     EXEC-PREFIX/bin

binary support utilities
     EXEC-PREFIX/lib/gnats

compiled libraries
     EXEC-PREFIX/lib

etc...

Since most installations are not intended to be distributed around a network, the default value for EXEC-PREFIX is the value of prefix, i.e., /usr/local.  However, using EXEC-PREFIX saves space when you are installing a package on several different platforms for which many files are identical; rather than duplicate them for each host, these files can be shared in a common repository, and you can use symbolic links on each host to find the host-dependent files.  It is not necessary to use this paradigm when building the GNATS tools.  See Configuring and compiling the software.

Use EXEC-PREFIX in conjunction with PREFIX to share host-independent files, like libraries and info documents.  For example:

        for each host:
     configure --prefix=/usr/gnu --exec-prefix=/usr/gnu/H-HOST
     make all install ...

Using this paradigm, all host-dependent binary files are installed into /usr/gnu/H-HOST/bin, while files which do not depend on the host type for which they were configured are installed into /usr/gnu.

You can then use a different symbolic link for /usr/gnu on each host (/usr is usually specific to a particular machine; it is always specific to a particular architecture).

       on host-1:
     ln -s /usr/gnu/H-HOST-1 /usr/gnu
       on host-2:
     ln -s /usr/gnu/H-HOST-2 /usr/gnu

To the end user, then, placing /usr/gnu/bin in her or his PATH simply works transparently for each HOST type.

You can change EXEC-PREFIX on the command line to configure using

     configure --exec-prefix=EXEC-PREFIX ...

We recommend that you consult Using configure (Cygnus configure), before attempting this. Again, it is not necessary to use this paradigm when building the GNATS tools.

GNATS_ROOT
==========

The location of the database and the administrative data files, by default PREFIX/lib/gnats/gnats-db.  You can change this value on the command line to configure using

     configure --with-gnats-root=GNATS_ROOT

Administrative data files reside in GNATS_ROOT/gnats-adm. These include categories, submitters, responsible, and config, as well as two files generated and maintained by GNATS, index and current.  See Changing your local configuration, and Administrative data files.

Default installation locations
==============================

PREFIX
     defaults to /usr/local; change using configure (see Configuring and compiling the software).

EXEC-PREFIX
     defaults to PREFIX; change using configure (see Configuring and compiling the software).

GNATS_ROOT
     defaults to PREFIX/lib/gnats/gnats-db; change using configure (see Configuring and compiling the software).

GNATS installs tools, utilities, and files into the following locations.

EXEC-PREFIX/bin

     send-pr
          See Submitting Problem Reports.

     edit-pr
          See Editing existing Problem Reports.

     query-pr
          See Querying the database.

     nquery-pr
          See Querying the database over the network.

EXEC-PREFIX/lib/gnats

     mkcat
          See Adding a problem category.

     rmcat
          See Removing a problem category.

     mkdist
          See Configuring send-pr for the outside world.

     gen-index
          See Regenerating the index.

     queue-pr
          See Handling incoming traffic.

     file-pr
          See Processing incoming traffic.

     at-pr
          See Timely reminders.

     pr-edit
          See The edit-pr driver.

     pr-addr
          See Address retrieval.

     libiberty.a
          The GNU libiberty library.

PREFIX/lib/gnats/dist

     A packageable distribution of send-pr.
          See Configuring send-pr for the outside world.

PREFIX/lib/gnats

     site
          The local list of valid categories, used by send-pr; SITE is the value of GNATS_SITE (see The config file).

PREFIX/lib/emacs/lisp

     gnats.el
     gnats.elc
          The Emacs versions of the programs query-pr, edit-pr, and view-pr.  See Invoking the GNATS tools.  To change this directory you must alter Makefile.in; see Configuring and compiling the software.

     send-pr.el
          The Emacs version of the program send-pr. See Submitting Problem Reports.

PREFIX/info

     gnats.info
     send-pr.info
          The GNATS manuals, in a form readable by info (the GNU hypertext browser).  See Reading GNU Online Documentation (GNU Online Documentation).

PREFIX/man/man1
PREFIX/man/man8

     man pages for all the GNATS tools and utilities.
          See Invoking the GNATS tools.

PREFIX/src

     Source code for GNATS.

PREFIX/sample

     Example administrative files, including categories,
          submitters, responsible, and config.  See Changing your local configuration.

GNATS_ROOT

     gnats-adm
          Administration and configuration data files.  The files

          config

          categories

          submitters

          responsible

          gnatsd.conf

          index
               (This file is created by GNATS.)

          current
               (This file is created by GNATS.)

          exist here.  See Changing your local configuration, and Administrative data files.

     gnats-queue
          Incoming Problem Reports are queued here until the next iteration of queue-pr -r (see Handling incoming traffic).

     pending
          Problem Reports which arrive without a valid category value are reassigned to the category pending and placed here pending intervention by the GNATS administrator. See GNATS administration.

     CATEGORY
          Each valid category has a corresponding subdirectory in the database. All Problem Reports associated with that category are kept in that subdirectory, along with lock files for PRs which are being edited.

Querying using regular expressions
**********************************

GNATS uses GNU regular expression syntax with these settings:

     RE_SYNTAX_POSIX_EXTENDED | RE_BK_PLUS_QM & RE_DOT_NEWLINE

This means that parentheses (( and )) and pipe symbols (|) do not need to be used with the escape symbol \.  The tokens + and ? do need the escape symbol, however.

Unfortunately, we do not have room in this manual for an adequate tutorial on regular expressions.  The following is a basic summary of some regular expressions you might wish to use.

See Regular Expression Syntax (Regex), for details on regular expression syntax.  Also see Syntax of Regular Expressions (GNU Emacs Manual), but beware that the syntax for regular expressions in Emacs is slightly different.

All search criteria options to query-pr rely on regular expression syntax to construct their search patterns.  For example,

     query-pr --state=open

matches all PRs whose >State: values match with the regular expression open.

We can substitute the expression o for open, according to GNU regular expression syntax.  This matches all values of >State: which begin with the letter o.

     query-pr --state=o

is equivalent to

     query-pr --state=open

in this case, since the only value for >State: which matches the expression o is open.  (Double quotes (") are used to protect the asterix (*) from the shell.)  --state=o also matches o, oswald, and even oooooo, but none of those values are valid states for a Problem Report.

Regular expression syntax considers a regexp token surrounded with parentheses, as in (REGEXP), to be a group.  This means that (ab)* matches any number of contiguous instances of ab, including zero.  Matches include, ab, and ababab.

Regular expression syntax considers a regexp token surrounded with square brackets, as in [REGEXP], to be a list. This means that Char[(ley)(lene)(broiled) matches any of the words Charley, Charlene, or Charbroiled (case is significant; charbroiled is not matched).

Using groups and lists, we see that

     query-pr --category="gcc|gdb|gas"

is equivalent to

     query-pr --category="g(cc|db|as)"

and is also very similar to

     query-pr --category="g[cda]"

with the exception that this last search matches any values which begin with gc, gd, or ga.

The . character is known as a wildcard.  . matches on any single character.  * matches the previous character (except newlines), list, or group any number of times, including zero. Therefore, we can understand .* to mean ``match zero or more instances of any character.''  For this reason, we never specify it at the end of a regular expression, as that would be redundant.  The expression o matches any instance of the letter o (followed by anything) at the beginning of a line, while the expression o.* matches any instance of the letter o at the beginning of a line followed by any number (including zero) of any characters.

We can also use the expression operator | to signify a logical OR, such that

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

matches all open or analyzed Problem Reports.  (Double quotes (") are used to protect the pipe symbol (|) from the shell.)

By the same token, (No pun intended.) using

     query-pr --state=".*a"

matches all values for >State: which contain an a.  (These include analyzed and feedback.)

Another way to understand what wildcards do is to follow them on their search for matching text.  By our syntax, .* matches any character any number of times, including zero.  Therefore, .*a searches for any group of characters which end with a, ignoring the rest of the field.  .*a matches analyzed (stopping at the first a) as well as feedback.

Note: When using --text or --multitext, you do not have to specify the token .* at the beginning of TEXT to match the entire field.  For the technically minded, this is because --text and --multitext use re_search rather than re_match.  re_match anchors the search at the beginning of the field, while re_search does not anchor the search.

For example, to search in the >Description: field for the text

     The defrobulator component returns a nil value.

we can use

     query-pr --multitext="defrobulator.*nil"

To also match newlines, we have to include the expression (.|^M) instead of just a dot (.).  (.|^M) matches ``any single character except a newline (.) or (|) any newline (^M).''  This means that to search for the text

     The defrobulator component enters the bifrabulator routine
     and returns a nil value.

we must use

     query-pr --multitext="defrobulator(.|^M)*nil"

To generate the newline character ^M, type the following depending on your shell:

csh
     control-V control-M

tcsh
     control-V control-J

sh (or bash)
     Use the RETURN key, as in

          (.|
          )

Again, see Regular Expression Syntax (Regex), for a much more complete discussion on regular expression syntax.