gnats(7)                                                 Problem Report Management System                                                 gnats(7)

NAME

       gnats - Problem Report Management System

DESCRIPTION

       GNATS  is  a  bug-tracking tool designed for use at a central support site.  Software users who experience problems use tools provided with
       GNATS to submit Problem Reports to the the maintainers of that software; GNATS partially automates the tracking of these problems by:

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

       o      allowing support personnel and their managers to edit, query and report on accumulated bugs; and

       o      providing a reliable archive of problems with a given program and a history of the life of the program by  preserving  its  reported
              problems and their subsequent solutions.

       GNATS offers many of the same features offered by more generic databases.  You can query and edit existing problem reports (PRs) as well as
       obtain reports on groups of PRs.  The database itself is simply an ordered repository for problem  reports;  each  PR  receives  a  unique,
       incremental PR number which identifies it throughout its lifetime.

       Many of the primary functions available with GNATS are accessible from within GNU Emacs.

PROBLEM REPORT STATES

       PRs go through several states in their lifetimes.  The set of states is site-specific.

       The default set of states are:

       open                the  initial  state  of  every PR; this means the PR has been filed and the person or group responsible for it has been
                           notified of the suspected problem

       analyzed            the problem has been examined and work toward a solution has begun

       feedback            a solution has been found and tested at the support site, and sent to the party who reported the problem; that party is
                           testing the solution

       closed              the solution has been confirmed by the party which reported it

       In some cases, it may be necessary to suspend work on a bug; in this case, its state changes to suspended rather than closed.

STRUCTURE

       Incoming  PRs  are  assigned  an  incremental  serial  number and filed according to category.  An index is kept concurrently to accelerate
       searches of the database.

       All GNATS administration and database files are located in subdirectories of a directory associated  with  each  database.   Databases  are
       named,  and  the  association  between  database names and directories is described by the databases file, which is found on this system in
       /usr/etc/gnats/databases.

       Problem Reports are segregated into subdirectories within the database directory by category.  For example, problems submitted with a cate-
       gory of gcc will be filed in the database subdirectory gcc.

       GNATS administration files are kept in the database subdirectory gnats-adm:

       addresses      contains mappings between submitter IDs and corresponding e-mail addresses

       categories     table of valid categories and parties responsible for them

       classes        table of valid classes of Problem Reports

       current        keeps track of incremental PR numbers assigned

       dbconfig       describes the structure of the database, and various database-specific options

       gnatsd.user_access
                      lists host names and access levels of hosts authorized to access the database

       gnatsd.user_access
                      lists user names, passwords and access levels of users authorized to access the database

       index          database index

       locks          directory containing lock files

       responsible    table of responsible parties and their email addresses

       states         table of valid states of Problem Reports

       submitters     database of sites which submit PRs

       Administrative  programs  and  programs internal to GNATS are kept in the directory /usr/libexec/gnats while those meant for public use are
       installed in /usr/bin.

       /usr/libexec/gnats contains the programs:

       mkdb           used by the GNATS administrator to create a new database

       mkcat          used by the GNATS administrator to create new categories [obsolete]

       rmcat          used by the GNATS administrator to remove outdated categories [obsolete]

       gen-index      used by the GNATS administrator to generate a new version of the index

       queue-pr       mail control program which accepts incoming messages and periodically submits them to the database via cron by feeding  them
                      through the program file-pr(8)

       pr-edit        program which is mainly responsible for editing existing PRs and filing new ones; it is used by edit-pr and file-pr

       file-pr        script which uses pr-edit to file new PRs

       at-pr          automatically notifies responsible parties if a PR is not analyzed within a requisite period defined in the submitters file

       delete-pr      used to delete closed PRs

       /usr/bin contains the programs

       query-pr       used to query the database

       edit-pr        used to edit individual PRs

       send-pr        used to submit problems to GNATS

       Documentation exists for all programs associated with GNATS.

SEE ALSO

       Keeping Track: Managing Messages With GNATS (also installed as the GNU Info file gnats.info)

       databases(5),  dbconfig(5),  delete-pr(8),  edit-pr(1) file-pr(8), gen-index(8), gnats(7), gnatsd(8), mkcat(8), mkdb(8), pr-edit(8), query-
       pr(1), queue-pr(8), send-pr(1).

HISTORY

       GNATS was greatly inspired by the BSD sendbug(1) and bugfiler(8) programs.  It was originally written in C++, Elisp, shell script, and awk.
       It presently consists of utilities written in C, shell script, and Elisp.

AUTHORS

       GNATS  was  originally  written by Heinz G. Seidl (Cygnus Support).  Subsequent iterations were developed by Brendan Kehoe (Cygnus Support)
       and Jason Merrill (Cygnus Support), with help from Tim Wicinski.  Documentation was initially developed by Jeffrey Osier  (Cygnus  Support)
       and Brendan Kehoe (Cygnus Support).

       Version  4.x  was  a  substantial  rewrite  done  by Bob Manson (Juniper Networks), Milan Zamazal and Yngve Svendsen (Clustra Systems / Sun
       Microsystems)

COPYING

       Copyright (c) 1992, 1993, 1999, 2000, 2003, Free Software Foundation

       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 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,  except  that  this  permission notice may be included in translations approved by the Free Software Foundation instead of in the
       original English.

GNATS                                                               August 2003                                                           gnats(7)