Bug Management With GNATS

GNU Problem Report Management System

Version 3.01

February 1993

Jeffrey M. Osier
Cygnus Support

Reporting Problems With send-pr is a separate manual which contains the same text as the chapter “Reporting problems with send-pr” in this manual, so that support sites who use GNATS may copy and distribute the send-pr manual when they distribute send-pr (see section Configuring send-pr for the outside world).

Throughout this manual, the personal pronouns you and your refer to the GNATS installer/administrator at a given site.

Copyright © 1993 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.


[ < ] [ > ]   [Contents] [Index] [ ? ]

Overview

This manual documents a suite of utilities called GNATS, the GNU Problem Report Management System. GNATS is a bug-tracking tool designed for use at a central support site. Software users who experience problems use electronic mail to communicate these problems to the maintainers of that software; GNATS partially automates the tracking of these problem reports (PRs) by:

GNATS offers many of the same features offered by more generic databases. 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. See section Invoking the GNATS tools. Also see for information about submitting problem reports from within Emacs.

Problem reports go through several defined states in their lifetimes. The database considers the initial state of every PR to be open; this means the PR has been filed and the person or group responsible for it has been notified of the suspected problem. Once the problem has been examined, its state changes to analyzed, and work toward a solution begins. When a solution has been found and tested at the support site, that solution is sent to the party who reported the problem (the submitter). The PR goes into feedback state until the solution is confirmed by the submitter, at which point the state changes to closed. In some cases, it may be necessary to suspend work on a bug; in this case, its state changes to suspended rather than closed. For a detailed explanation of what each state means, see States of Problem Reports.

Please report all bugs to one of these addresses:

bug-gnats@prep.ai.mit.edu 
{ucbvax|mit-eddie|uunet}!prep.ai.mit.edu!bug-gnats 

This manual documents the 3.01 release of GNATS.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1 Introducing GNATS

Any support site which supports more than one product or category of products realizes that a large amount of data flows back and forth in the form of problem reports and communication between software maintainers and software users. GNATS addresses the problem of organizing this communication by defining a database made up entirely of messages filed automatically by electronic mail.

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


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.1 The database paradigm

It is in the best interests of any software maintainer to make it easy for users of her or his software to report problems they might have with that software. It is also in her or his best interest to keep track of reported problems in as organized a fashion as possible. GNATS makes this easy by automatically filing incoming bug reports into proper places, and making them accessible to queries and easily editable. It 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 PRs in the form of text files with defined fields. Each bug report resides in a separate file within a main repository; editing access to the database is regulated to maintain consistency. The fields GNATS recognizes are discussed in GNATS data fields. We provide edit-pr with this distribution as a tool for software maintainers to use when editing problem reports in the database. Maintainers can use query-pr for making inquiries about certain PRs or groups of PRs with a very fast search mechanism based on an index which is kept constantly up to date.

At the support site, a GNATS administrator is charged with the duty of maintaining GNATS. These duties are discussed in detail in Managing GNATS, and generally include pruning log files, setting up new categories for GNATS to handle, and handling bug reports that arrive in a format GNATS cannot understand.

Responsibility for a given problem report is determined by 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 section Configuring and installing GNATS, and Data Flow.

The tool send-pr is provided with this distribution so that both submitters may more easily submit bug reports that will have fewer problems when being filed into the database. send-pr is both a shell script and a GNU Emacs mode; both implementations provide a template for submitters to complete. In most cases, send-pr will be able to “figure out” the values of several fields, thus at least partially automating the bug-reporting process. Of course, any editor and mailer may be used to submit problem reports to the database. However, the default values GNATS assigns to partially formatted PRs are not always correct for each PR. send-pr is easy to use; it brings up a template which prompts a user for certain useful kinds of information, which is a step forward in the process of knowing what kind of data to provide. (The send-pr manual also provides a “Helpful Hints” chapter to help people to decide what kinds of information to provide in reporting bugs;

We also provide a utility called mkdist, which constructs a complete distribution of send-pr, including documentation, customized to your site’s combination of categories. See section Configuring send-pr for the outside world.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.2 Data Flow

Once you configure GNATS to reflect the categories of problem reports you wish to accept and the responsible parties, you can start accepting problem reports from both internal and external sources.

For a flowchart describing the activity of GNATS, see Flowchart of GNATS activities.

All incoming problem reports should be directed to a single mail alias which you determine when configuring GNATS for your site. This alias pipes incoming reports into a program called queue-pr, which places them in the subdirectory ‘gnats-queue’ under the root GNATS directory. The program queue-pr is also run periodically via cron with a different option; this iteration of queue-pr feeds the queued PRs in ‘gnats-queue’ to the program file-pr, which assigns each bug report an incremental identifying number and places it in the database according to its category, updating the index as well. file-pr also forwards a copy of the bug report to the person responsible for solving the problem, and optionally sends an acknowledgment to the submitter of the problem report. The GNU Problem Report Tracking System does not yet have the ability to decipher random text, so any problem reports which arrive in a format GNATS does not recognize are kept in a separate directory pending investigation by the GNATS administrator. This directory is called, creatively enough, ‘pending’.

Depending on your configuration, gnats may invoke at-pr, which, if a bug is listed with ‘>Priority: high’ or ‘Severity: critical’, sends a reminder to the person responsible for the bug report if it isn’t analyzed within a certain requisite time period (relative to the submitter of the bug; see section The submitters file). at-pr creates a queued job using at which, after the allotted time (in business hours, 8am to 5pm Monday through Friday) is past, checks the PR to see if its state has changed from ‘open’. If this hasn’t occurred, at-pr sends mail to the responsible person and to gnats-admin with the following message:

To: originator responsible gnats-admin
Subject: PR id-number not analyzed in #hours hours

PR id-number was not analyzed within the acknowledgment period
of #hours business hours.  The pertinent information is:

 Submitter-Id: submitter
 Originator: full name of the submitter
 Synopsis: synopsis
 Person responsible for the PR: responsible

--
The GNU Problem Report Tracking System (GNATS)

At this point, the bug report has been filed, the responsible parties have been notified, and an acknowledgment has been sent to the submitter of the problem report. The state of the PR is ‘open’, and it is up to the responsible person to contact the submitter for any more information needed to analyze the problem. Any further mail should be carbon-copied to the GNATS mailing address as well, with the category and id-number in the Subject line of the message:

To: submitter@submitter-site
From: responsible (or anyone wishing to reply to this message)
Subject: Re: PR category/id-number: original message subject
Cc: GNATS address

message…

This message is automatically appended to the Problem Report in the ‘>Audit-Trail:’. Messages are recorded there in the order received. If the the PR in question is being edited when a reply comes in, that message is placed in the queue to be appended to the PR whenever queue-pr is run again.

In order to maintain consistency, any large code samples or test cases should reside in a separate directory. One strategy is to create a directory called ‘test-cases’ or something similar in the home directory of GNATS, with subdirectories in each named ‘id-number-d’, storing all extra information according to the PR identification number with which the information is related. Be sure to note in the PR that the other information exists, and where. For example:

gnats% ls -F ./test-cases
128-d/      432-d/      872-d/     1102-d/
322-d/      778-d/      995-d/

where each of these directories contains test cases which exhibit the problem reported.

Software maintainers use the program edit-pr to alter fields in certain PRs, and the program query-pr to obtain information from the database. query-pr --summary may also be used to generate a one-line summary of each PR in the search, which can then be used with awk or sed to create reports on the database:

query-pr --summary --state=open > Open-bugs
query-pr --summary --state=analyzed > Analyzed-bugs
cat Open-bugs Analyzed-bugs | awk -f ./bugsort.awk > current-bugs

GNATS sends notifications of any changes in the state or responsibility fields to the responsible party and to the submitter of the bug report.

Maintainers now begin work on the bug, at first analyzing the problem (and thus changing the state of the PR to analyzed) and then seeking a solution for it. Once a PR is analyzed, work begins toward a solution. When the solution is found, the maintainer changes the state to feedback and provides the solution to the submitter of the bug report so that it may be tested; when the submitter confirms that the solution works, the state may be changed to closed. If for some reason the progress towards a solution must be stopped, the state can be changed to suspended. See section States of Problem Reports.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.3 Flowchart of GNATS activities


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.4 States of Problem Reports

Each PR goes through a defined series of states between origination and closure, and is considered active until it has been resolved or otherwise explicitly closed. The originator of a PR receives notification automatically of any state changes that occur.

open

The initial state of a Problem Report. This means the PR has been filed and the responsible person(s) notified.

analyzed

The responsible person has analyzed the bug. The analysis should contain a preliminary evaluation of the problem and an estimate of the amount of time and resources necessary to solve the problem. It should also suggest possible workarounds.

feedback

This state indicates that the problem has been solved, and the originator has been given a patch or other fix. The PR remains in this state until the originator acknowledge that the solution works.

closed

A Problem Report is closed (“the bug stops here”) only when any changes to the software in question have been documented, integrated and tested, and the submitter has confirmed the solution.

suspended

Work on the problem has been postponed. This happens if a timely solution is not possible or is not cost-effective at the present time. The PR continues to exist, though a solution is not being actively sought. If the problem cannot be solved at all, it should be closed rather than suspended.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5 GNATS data fields


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5.1 Mail Header fields

A Problem Report may contain any mail header field described in the Internet standard RFC-822. However, only the fields which identify the sender and the subject are required for send-pr to function properly:

To:

The preconfigured mail alias for the support site where the PR is to be sent, automatically supplied by send-pr.

Subject:

A terse description of the problem.

From:

Usually supplied automatically by the originator’s mailer; should contain the originator’s electronic mail address.

Reply-To:

A return address to which electronic replies can be sent; in most cases, probably the same address as the From: field.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

1.5.2 Problem Report fields

Problem Report fields begin with a keyword enclosed with ‘>’ and ‘:’, and belong to one of three data types:

ENUMERATED

One of a specific set of values. The value must be on the same line as the keyword. For each ENUMERATED keyword, the possible choices are listed in the send-pr template as a comment.

STRING

One single line of text which must begin and end on the same line as the keyword.

TEXT

Text of any length may occur in this field. TEXT may span multiple lines and may also include blank lines. A TEXT field ends only when another keyword appears.

The following fields are present whenever a PR is submitted via the program send-pr. GNATS adds additional fields when the PR arrives at the support site; explanations of these follow this list.

>Submitter-Id:

(ENUMERATED) A unique identification code assigned by the support site. It is used to identify all Problem Reports coming from a particular site. (Submitters without a value for this field can invoke send-pr with the ‘--request-id’ option to apply for one from the support organization. Problem Reports from those not affiliated with the support organization should use the default value of ‘net’ for this field.)

>Originator:

(STRING) Originator’s real name. The default is the value of the originator’s environment variable NAME.

>Organization:

(TEXT) The originator’s organization. The default value is the contents of the originator’s environment variable ORGANIZATION, or the contents of the file ‘.signature’ if ORGANIZATION isn’t set.

>Confidential:

(ENUMERATED) Use of this field depends on the originator’s relationship with the support organization; contractual agreements often have provisions for preserving confidentiality. Conversely, a lack of a contract often means that any data provided will not be considered confidential. Submitters should be advised to contact the support organization directly if this is an issue.

If the originator’s relationship to the support organization provides for confidentiality, then if the value of this field is ‘yes’ the support organization treats the PR as confidential; any code samples you provide are not made publicly available (e.g., in regression test suites). The default value is ‘yes’.

>Synopsis:

(STRING) One-line summary of the problem.

>Severity:

(ENUMERATED) The severity of the problem. Accepted values include:

critical

The product, component or concept is completely non-operational or some essential functionality is missing. No workaround is known.

serious

The product, component or concept is not working properly or significant functionality is missing. Problems that would otherwise be considered ‘critical’ are rated ‘serious’ when a workaround is known.

non-critical

The product, component or concept is working in general, but lacks features, has irritating behaviour, does something wrong, or doesn’t match its documentation.

The default value is ‘serious’.


>Priority:

(ENUMERATED) How soon the originator requires a solution. Accepted values include:

high

A solution is needed as soon as possible.

medium

The problem should be solved in the next release of the software.

low

The problem should be solved in a future release.

The default value is ‘medium’.


>Category:

(ENUMERATED) The name of the product, component or concept where the problem lies. The support organization provides a list of valid categories; use ‘send-pr -L’ to see the listing provided with the send-pr distribution. For an example list, see


>Class:

(ENUMERATED) The class of a problem can be one of the following:

support

A support problem or question.

sw-bug

A software bug.

doc-bug

A bug in the documentation.

change-request

A request for a change in behavior, etc.

mistaken

No bug, user error or misunderstanding. This value is valid only at the support site.

duplicate (pr-number)

Duplicate PR. pr-number should be the number of the original PR.

The default is ‘sw-bug’.


>Release:

(STRING) Release or version number of the product, component or concept.

>Environment:

(TEXT) Description of the environment where the problem occured: machine architecture, operating system, host and target types, libraries, pathnames, etc.

>Description:

(TEXT) Precise description of the problem, including all preconditions, inputs, outputs, conditions after the problem, and symptoms. Any additional important information should be included. In the send-pr manual, users are instructed to include all the details that would be necessary for someone else to recreate the problems they report, however obvious. Sometimes seemingly arbitrary or obvious information can point the way toward a solution. For the types of information to include, see

>How-To-Repeat:

(TEXT) Example code, input, or activities to reproduce the problem. The support organization uses your example code both to reproduce the problem and to test whether the problem is fixed. Again, see for helpful hints.

The following fields are added to the PR when the support site receives it:

>Responsible:

The person responsible for this category, as noted in the ‘categories’ file.

>Arrival-Date:

The time that this PR was received by GNATS.

>Audit-Trail:

Tracks changes in ‘>State:’ and ‘>Responsible:’ with the sub-fields:

State-Changed-<From>-<To>: <oldstate>-<newstate>
Responsible-Changed-<From>-<To>: <oldresp>-<newresp>

ENUMERATED field containing the values the state or responsible was changed from and to.

State-Changed-By: name
Responsible-Changed-By: name

ENUMERATED field containing the name of the maintainer who affected the change.

State-Changed-When: date and time
Responsible-Changed-When: date and time

STRING containing the time the change was made.

State-Changed-Why: reason…
Responsible-Changed-Why: reason…

TEXT field with the reason for the change.

Also contains any mail messages received by GNATS related to this PR, in the order received.

>Unformatted:

Any information that does not fit into any of the above fields.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2 Configuring and installing GNATS

There are several steps you need to go through to fully configure and install GNATS on your system. You will need root access in order to make a new account for gnats, to allow this “user” access to cron and at, and to install the GNATS utilities. You may need root access on some systems in order to set mail aliases in place.

  1. First, unpack your distribution.
    Whether the distribution you receive is on a tape or from the Net, all the sources reside in a directory called ‘gnats-3.01’ when unpacked. We will call this the “top level” of the source directory, or srcdir. The sources for the GNATS tools are in the subdirectory ‘gnats-3.01/gnats/*’.

    Lists of files included in the distribution are in each directory in the file ‘MANIFEST’.

  2. From the top level of the source directory, edit ‘gnats/Makefile.in.
    In the file ‘gnats-3.01/gnats/Makefile.in’, set the following variables (do not edit any other ‘Makefile’ in the distribution):
    GNATS_ROOT

    The directory where the database, all administration files, etc., resides. After installing, any changes should be made in this directory. From now on, we will refer to this directory as GNATS_ROOT.

    GNATS_ADDR

    The address to which software users should submit bugs. For instance, if you wish all problem reports to be sent to your site at ‘bug-reports@your-organization’, this full address should be the value of GNATS_ADDR.

    GNATS_SITE

    A one-word name tag for your site, to be used as an alias for anyone who submits bug reports. You should also include this name in the ‘submitters’ file so GNATS can recognize bug reports originating from inside your organization (see step 12). This value also becomes the name of a list of categories your organization supports, which is kept up to date locally when you run the program mkcat (see section The categories file) and is created for outside users when you use the utility mkdist (see section Configuring send-pr for the outside world).

    DEFAULT_RELEASE

    Used by send-pr as a default value for the ‘>Release:’ field. Use the name or release number of your most recent release, or just leave it blank to set no default.

    DEFAULT_ORGANIZATION

    Used by your local send-pr as a default value for the ‘>Organization:’ field. Supply the name of your organization here.

    This is the only ‘Makefile’ you should edit in this distribution.

  3. Edit the file ‘gnats-3.01/gnats/config.h.
    This file contains variables which establish some behavior traits of GNATS. See section The config.h file.
  4. Run configure at the top level.
    You can nearly always run configure from the top level of the source directory, ‘gnats-3.01’, with the command
    ./configure hosttype
    

    (where hosttype is your host type) and the “Right Thing” will happen: GNATS will be configured in the same directory you unpacked it in; when built, it will be able to run on the machine you’re building it on; and when installed, files which should be public will be installed in ‘/usr/local’. You may omit hosttype on most platforms; configure has magical ways of finding out what kind of machine you’re on.

    You may wish to build GNATS in a different directory from the source directory, or install the user utilities like query-pr in a directory different from ‘/usr/local’. For instructions on this, see Configuring GNATS on your system.

  5. Run make all at the top level.
    Do not run make install at this point, as installation must be done with root privileges.

The following steps may require root privileges.

  1. su root to acquire root privileges.
  1. Create a ‘passwd’ entry for gnats.
    In other words, create an account for a user named “gnats”. The home directory for this account should be the same directory you specified for GNATS_ROOT in the file ‘Makefile.in’. Also, the default path for this “user” should contain ‘GNATS_ROOT/gnats-bin’.
  1. Run
    make install GNATS=install-gnats
    

    from the top level of your source directory. This installs GNATS in the directory you specified with ‘GNATS_ROOT’. It also installs the other files associated with GNATS, including the program send-pr, the GNU library ‘libiberty’, and several others.

  1. Allow cron and at commands for the user gnats.
    GNATS requires access to both cron and at, so it may be necessary to explicitly allow the user gnats access by adding it to the files ‘/var/spool/cron/cron.allow’ and ‘at.allow’, if these files exist. If they do not exist, and the name gnats does not appear in the corresponding files ‘cron.deny’ or ‘at.deny’, then no further action is necessary.
  1. 10
  2. If you need to use GNATS utilities, like query-pr and edit-pr, on other systems besides the one GNATS itself resides on, see Using GNATS over a network.
  1. 11
  2. Create an alias for gnats-admin, the GNATS administrator, in the file ‘/etc/aliases’, or wherever your mail system looks for mail aliases. Assign this alias to the person in charge of GNATS. See section Managing GNATS.
  1. 12
  2. Create an alias to redirect incoming bugs. This alias should redirect incoming mail via a pipe to the program ‘queue-pr -q’. For example, if PRs coming to your site are to arrive at the address ‘bugs@your.company.com’, create an alias to the effect of:
    bugs:     "| GNATS_ROOT/gnats-bin/queue-pr -q > /dev/null 2>&1"
    

    where GNATS_ROOT is the directory where GNATS resides, which you indicated in the file ‘Makefile.in’. This places all incoming bugs in the directory ‘GNATS_ROOT/gnats-queue’.

  1. 13
  2. Create an alias for your site.
    This name should be the same name you indicated in ‘Makefile.in’ above with the variable GNATS_SITE, with the suffix ‘-gnats’, and should point toward the local submission address. For instance, if your site is Killer Technologies, the presence of GNATS on your site would be aliased as
    bugs:      "| GNATS_ROOT/gnats-bin/queue-pr -q > /dev/null 2>&1"
    killer-gnats: bugs
    

    The report-submission utility send-pr automatically appends the ‘-gnats’ to any arguments you specify. The send-pr which was installed when you typed make install has a default argument of GNATS_SITE, your site, so that when your local users simply type send-pr mail will be sent to your local GNATS. Part of the installation process for send-pr is to set up an alias for the support site they received send-pr from, so that anyone you distribute send-pr to will be instructed to make an alias

    killer-gnats: bugs@killer.com
    

    This allows users at your site, as well as anyone to whom you distribute send-pr, to type send-pr killer on the command line and submit PRs to your site. This aliasing allows your organization and its affiliates to use the same send-pr to submit bugs to more than one support site. For instance, if you also submit PRs to a GNATS located at Bumblebee BASIC, Inc., and Unencumbered Unix (a well-known supporter of Free Software), your ‘/etc/aliases’ file might resemble something like the following:

    # local and external GNATS sites
    # local first
    bugs:      "| GNATS_ROOT/gnats-bin/queue-pr -q > /dev/null 2>&1"
    killer-gnats:       bugs
    # other sites
    bumblebee-gnats:    bumblebugs@bumblebee.com
    unencumbered-gnats: unencumberbugs@unencumbered.org
    

    With these aliases, your users may simply type send-pr bumblebee to send Problem Reports to Bumblebee BASIC, or more precisely to bumblebugs, their GNATS alias.

    Anyone who receives send-pr from you will have a copy of send-pr which sends mail by default to ‘bugs@killer.com’. If these outside folk run GNATS themselves, it is up to the system administrator at each local site to decide on a default address. See also Introducing GNATS, for more discussion on the GNATS paradigm.

  1. 14
  2. You may also wish to forward a copy of each incoming Problem Report to a log. This can be accomplished via the mail aliases function with something like:
    bugs-q:  "| GNATS_ROOT/gnats-bin/queue-pr -q > /dev/null 2>&1"
    bugs-log:    GNATS_ROOT/bug.log
    bugs:        bugs-q, bugs-log
    

    where GNATS_ROOT is the directory GNATS resides in, which you specified in the file ‘gnats-3.01/gnats/Makefile.in’. This configuration will archive mail in the file ‘GNATS_ROOT/bug.log’, and also feed it to the program queue-pr. (Remember, ‘bug.log’ needs to be world-writable, and should be pruned regularly; see section Managing GNATS.)

  1. 15
  2. Exit from the root shell.
  1. 16
  2. Log in as gnats, the new account you created.
  3. Edit the files you just installed in ‘GNATS_ROOT/gnats-adm.
    You will need to edit:

    to reflect your schema for collecting data. See section Files used for GNATS administration, for detailed discussions of the formats of these files. For more discussion on data collection schematics, see Introducing GNATS.

  4. Run GNATS_ROOT/gnats-bin/mkcat.
    mkcat sets up the subdirectories of GNATS_ROOT which will contain submitted Problem Reports. Each subdirectory is named for the category its bugs will belong to; for instance, all bugs submitted with a category of carbuerator will be filed in the directory ‘GNATS_ROOT/carbuerator’. mkcat creates these directories according to the data you placed in the ‘categories’ file (see section The categories file); it also updates the local list of supported categories used by send-pr.

    Always run mkcat whenever you need to add a new category. See section Managing GNATS.

  5. Create a crontab entry for the user gnats to periodically run the command
    GNATS_ROOT/gnats-bin/queue-pr -r
    

    The ‘-r’ option causes queue-pr to feed all the incoming bugs from the directory ‘GNATS_ROOT/gnats-queue’ into the program file-pr, which assigns each new bug an individual serial number, notifies responsible parties of the existence of this bug, updates the index, files the bug in the correct subdirectory, etc. See section Introducing GNATS.

  6. Log out from the gnats account.

GNATS is now “live” on your system. The program send-pr (invoked with M-x send-pr from within Emacs) allows your local users to easily submit Problem Reports. You should pre-configure and distribute copies of send-pr to all parties you wish to receive bug reports from using the program mkdist; see Configuring send-pr for the outside world. See also


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1 Configuring GNATS on your system

See What configure does in Cygnus configure, for detailed information about configure.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1.1 Changing the installation location

/usr/local’ is the default installation directory, which can be altered by invoking configure with

./configure hosttype --prefix=install-dir 

where install-dir is the alternative installation directory. Nearly all files associated with GNATS are installed in the directory you indicated with GNATS_ROOT. The only files which are installed in the file indicated with ‘prefix’ are:

send-pr
query-pr
edit-pr

installed in ‘prefix/bin

libiberty.a

installed in ‘prefix/lib

categories-list

named the value of GNATS_SITE, installed and updated by mkcat in ‘prefix/lib/gnats

gnats.el
send-pr.el

installed in ‘prefix/lib/emacs/lisp’ (for information on byte-compiling these files, see Lisp Libraries in GNU Emacs)

gnats.info, send-pr.info

installed in ‘prefix/info

GNATS ``man'' pages

installed in ‘prefix/man/manN’, where N refers to the “man” section (“1” for commands, “8” for admin utilities, etc.).

It is not advised to change the values of these directories except through the use of the flag ‘--prefix=dir’. All other programs and files associated with GNATS are installed under the directory you indicated in ‘Makefile.in’ with the variable ‘GNATS_ROOT’.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1.2 Changing the build directory

You may choose to build GNATS in a different location from the source code. In this case, you must first create the new build directory, then call configure from there:

mkdir build-directory
cd build-directory
srcdir/configure hosttype --srcdir=srcdir

where srcdir is the top level of the directory holding the GNATS distribution. The build directory is always your current directory when you call configure.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.1.3 Other flags to configure

You can also use the following flags to configure. None will actually cause configure to configure your GNATS directory.

-V or --version

Prints out the version number of configure.

--help

Prints out a list of all the flags configure recognizes. Many are not applicable to GNATS.

The documentation for configure is included with this distribution in the directory ‘srcdir/gnats-3.01/etc’, and is installed when GNATS is installed. See What configure does in Cygnus configure.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.2 Using GNATS over a network

In order to install GNATS for use on a network, you may need root privileges on each host you wish to install on.

  1. Make sure the directory in which GNATS resides is NFS-mounted to each system that will need access to it, so GNATS_ROOT will be the same for each host. (This can be done with symbolic links as well.)
  2. Either NFS-mount your source and build directories, or make a copy of the GNATS source code tree in a separate directory on each system you wish to build on.
  3. For each host, do the following:
    configure hosttype (for the new host type)
    make all GNATS=all-tools
    su root on the new host
    make install GNATS=install-tools
    exit from the root shell

    This does a normal make all and make install for all files except those in the directory ‘srcdir/gnats’, which will only install:

    query-pr

    into ‘prefix/bin

    edit-pr

    into ‘prefix/bin

    pr-edit

    into ‘prefix/lib/gnats

    pr-addr

    into ‘prefix/lib/gnats

    gnats.el
    send-pr.el

    into ‘prefix/lib/emacs/lisp’ (for information on byte-compiling these files, see Lisp Libraries in GNU Emacs)

    on each system.

  4. Make sure you’re back on the host GNATS will run on.

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.3 The config.h file

The file ‘gnats-3.01/gnats/config.h’ is used as a header file where you may define certain local conventions you wish to implement or suppress. The only local conventions switchable by this file are the following:


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4 Files used for GNATS administration

The following files are located in ‘GNATS_ROOT/gnats-adm’, where GNATS_ROOT is the resident directory of GNATS. See section Introducing GNATS, to see how these files interact.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4.1 The categories file

This file contains a list of problem categories, specific to your site, which GNATS will track. You must edit this file initially, creating valid categories and then running ‘GNATS_ROOT/gnats-bin/mkcat’ to create the corresponding subdirectories of GNATS_ROOT. To create a new category once the system is in place, simply log in as gnats, add a line to this file, and run mkcat. Lines beginning with a ‘#’ will be ignored.

Its consists of four fields delineated with colons, as follows:

category:description:responsible:notify
category

A unique, valid category name, which can contain only text characters, dashes, underbars, etc., and cannot contain spaces or any of the following characters:

! $ & * ( ) { } [ ] ` ' " ; : < > ~

Ideally, category names should not contain commas or begin with periods. Each line will have a corresponding subdirectory in the main GNATS directory (GNATS_ROOT).

description

A terse textual description of the category.

responsible

The name tag of the party responsible for this category of problems, as listed in the ‘responsible’ file.

notify

One or more other parties which should be notified when a bug with this category arrives, such as a project manager, other members of the same project, other interested parties, or even log files. These should be separated with commas.

A good strategy for configuring this file is to have a different category for each product your organization supports or wishes to track information for, or perhaps with sub-categories within each category. For instance, if you wish to track documentation bugs in a variety of areas, you could have entries such as

doc:General Doc Questions:myboss:me, mypal
doc-rock:Doc for ROCK program:me:myboss
doc-stone:Docs for STONE utilities:mypal:fred@bedrock.com
doc-local:in-house documentation:me:doc-local-log

In the above example, bugs sent with a category of ‘doc’ are sent to the local mail address (or alias) ‘myboss’, and also sent to the addresses ‘me’ and ‘mypal’. Bugs with a category of ‘doc-rock’ are sent to the local addresses ‘me’ and ‘myboss’ only, while PRs sent with the category ‘doc-stone’ are sent outside the local organization as well as to ‘mypal’. PRs arriving for the category ‘doc-local’ are sent only to ‘me’, and are also sent to doc-local-log (in this case, an alias should be set up in ‘/etc/aliases’ to reflect a location for the log file, such as ‘doc-local-log: /users/me/local-log’).

Whenever you add a new category, be sure to run

GNATS_ROOT/gnats-bin/mkcat

to create a subdirectory for it and update the local categories list.

Only one category must be present for GNATS to function:

pending:Category for faulty PRs: gnats-admin:

The ‘pending’ directory is created automatically when you run make install.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4.2 The responsible file

This file contains a list of the responsible parties. Lines beginning with a ‘#’ will be ignored. Each entry contains three fields, separated by colons:

responsible:full-name:mail-address
responsible

A name-tag description of the party in question, such as her or his user name, or the name of the group. This name will be listed in the PR in the ‘Responsible’ field.

full-name

The full name of the party (“Butch Cassidy”; “Compiler Group”).

mail-address

The full, valid mail address of the party. This field is only necessary if the responsible party has no local mail address or alias.

A sample ‘responsible’ listing might be:

ren:Ren Hoek:
stimpy:Stimpson J. Cat:stimpy@lederhosen.org

Here, ren is a local user. stimpy is remote, so his full address must be specified.

The following entry must be present for GNATS to function:

gnats-admin: GNATS administrator:

(Remember, you put in gnats-admin as a mail alias, so for this purpose gnats-admin is a local address.)


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4.3 The submitters file

This is an optional database of sites which submit bugs to your support site. It contains six fields delineated by colons. Lines beginning with a ‘#’ will be ignored.

Entries are in the format:

submitter-id:name:type:resp-time:contact:notify
submitter-id

A unique identifier for a specific site or other entity which will be submitting Problem Reports.

name

A textual description of this entity.

type

Optional description for the type of relationship this submitter to your support site. This could indicate a contract type, a level of expertise, etc.

resp-time

GNATS is capable of reminding responsible parties of bugs marked with a ‘>Severity’ value of ‘critical’, or those with a ‘>Severity’ of ‘serious’ and a ‘>Priority’ value of ‘high’, when these bugs are not analyzed within a certain period. This argument, in business hours, defines that response period. This function is active if the NOTIFY field is defined as ‘TRUE’ in ‘config.h’ at build-time; see The config.h file. If NOTIFY is ‘FALSE’, this field is ignored. For information on at-pr, the program which sends out this reminder, see Introducing GNATS.

contact

The name tag of the “main contact” at the support site for this submitter. This contact should be in the ‘responsible’ file. Incoming bugs from submitter will be sent to this contact. Optionally, this field can be left blank.

notify

Any other parties which should receive copies of Problem Reports sent in by submitter.

A few example entries in the ‘submitters’ file:

univ-hell: University of Southern Hades::3:beelzebub:lucifer
tta: Telephones and Telegraphs of America:support:720:dave:

In this example, when a PR comes in from the University of Hades, it should have ‘univ-hell’ in its ‘Submitter-Id’ field; this bug will go to beelzebub (who should be in the ‘responsible’ file), and if it is not analyzed within three hours a reminder message will be sent. lucifer also receives a copy of the bug, and a copy of the reminder message as well (if it is sent). When Telephones and Telegraphs of America utilizes their “support” contract and submits a bug, a copy is sent only to dave, who has 720 hours to return an analysis before a reminder is sent.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4.4 The index file

The index is used to accelerate searches on the database. This file is not created until the first PR comes in. It is then kept up to date by GNATS; you should never touch this file.

Any searches on subjects contained in the index will be much faster than searches which depend on data not in the index. The index contains entries for: id-number; category; responsible; submitter; state; class; and severity.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

2.4.5 The current file

This file contains the last serial number assigned to an incoming PR. It is used internally by GNATS; you need never touch this file.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3 Invoking the GNATS tools

The following programs comprise GNATS:

send-pr

Used by anyone who has a problem with a given set of software to submit a report of the problem to the maintainers of that software

query-pr

Used by software maintainers to query the GNATS database (see section Querying individual Problem Reports).

edit-pr

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

mkcat

Used by the GNATS administrator when creating new categories (see section The categories file).

rmcat

Does the opposite of mkcat, i.e. removes categories (see section Managing GNATS).

mkdist

Used by the GNATS administrator when creating a distribution of the program send-pr for offsite submitters of PRs (see section Configuring send-pr for the outside world).

gen-index

Used by the GNATS administrator if the index file becomes corrupted, or if an up-to-date copy of it is wanted for some reason. gen-index builds an index and prints it to the standard output (see section Managing GNATS).

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 (see section Introducing GNATS).

file-pr

The internal program which files Problem Reports as they come in (see section Introducing GNATS).

at-pr

Used internally by GNATS to send reminders to maintainers based on quoted response times (see section Introducing GNATS).

pr-edit

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

pr-addr

Provides a valid electronic mail address for a given responsible name tag. Information is drawn from the file ‘GNATS_ROOT/gnats-adm/responsible’. Used internally.

Of these, only send-pr, query-pr, and edit-pr are installed in a public directory. The database itself is write-protected solely to maintain data consistency. mkcat, rmcat, gen-index and mkdist are designed for use by a database or system administrator, while at-pr, pr-edit, pr-addr, file-pr, and ‘queue-pr -q’ are completely internal and not meant to be called by hand. ‘queue-pr -r’ can be run by hand, but it is usually easiest to let it run periodically via cron.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1 Querying individual Problem Reports

You can obtaining data from the database through the program query-pr, which uses the search parameters you provide with options and/or arguments to find matching Problem Reports in the database. You can invoke query-pr from within Emacs as well as from the shell.

All arguments to query-pr are optional. If you don’t specify a PR and don’t give any search parameters, query-pr will display the entire database. All arguments are considered as PR numbers to display. Any number of options can be given; all are connected with a logical AND.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1.1 Invoking query-pr

query-pr uses the same arguments whether it is invoked from the shell or from Emacs. From the shell, simply type query-pr, followed by any search parameters you wish to exercise. From Emacs, type M-x query-pr, and you will be prompted for search parameters in the minibuffer. Use

C-x `     or
M-x next-error

to scroll through the matching PRs.

The usage for query-pr is:

query-pr  [gnats-id] [-i | --sql] [-F | --full]
          [-d directory | --directory=directory]
          [-c category | --category=category]
          [-S submitter | --submitter=submitter]
          [-r responsible | --responsible=responsible]
          [-s state | --state=state]
          [-C [yes | no] | --confidential=[yes | no]]
          [-e severity | --severity=severity]
          [-p priority | --priority=priority]
          [-O originator | --originator=originator]
          [-o outfile | --output=outfile]
          [-P | --print-path]
          [-x | --skip-closed]
          [-q | --summary]
          [-V | --version] [-h | --help ]

Without the ‘-F’ or ‘--full’ option, query-pr will only display a “header” for each PR which meets the search criteria. Any number of the options listed may be included in the search criteria.

gnats-id

The identification number of the PR you wish to view.

-i
--sql

Prints information in a form readable by an SQL database; see Example queries.

-F
--full

Prints the full Problem Report rather than just summary information.

-d directory
--directory=directory

Changes the directory to directory from GNATS_ROOT.

-c category
--category=category

Search only for PRs with a ‘Category’ field of category.

-S submitter
--submitter=submitter

Search only for PRs with a ‘Submitter’ field of submitter.

-r responsible
--responsible=responsible

Search only for PRs with a ‘Responsible’ field of responsible.

-s state
--state=state

Search only for PRs with a ‘State’ field of state. Values will be one of: open, analyzed, suspended, feedback, or closed.

-C [yes | no]
--confidential=[yes | no]

Search only for PRs with a ‘Confidential’ field of either yes or no. If this option is not given, all PRs will be eligible for the search regardless of their confidentiality.

-e severity
--severity=severity

Search only for PRs with a ‘Severity’ field of severity. Values will be one of: critical, serious, or non-critical.

-p priority
--priority=priority

Search only for PRs with a ‘Priority’ field of priority. Values will be one of: high, medium, or low.

-O originator
--originator=originator

Search only for PRs with an ‘Originator’ field of originator. Since this option does not reference the index, queries using it will be much faster if another search criterion is used that is part of the index.

-o outfile
--output=outfile

Print all output to outfile rather than to the standard output.

-P
--print-path

Prints the path which query-pr used to find the current PR. A line of the form ‘directory/number:number’ will be printed before each PR. You will probably never want to use this option; it is automatically used from within Emacs to facilitate scrolling through groups of PRs with C-x `.

-x
--skip-closed

Omit closed PRs from the search path. This option is ignored if you are doing a search on the ‘>State:’ field (using ‘-s’ or ‘--state=state’).

-q
--summary

Print a short single-line summary of PR information.

-V
--version

Print the version number of query-pr.

-h
--help

Print a brief usage summary.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.1.2 Example queries

The following query:

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

yields all PRs in the database which contain the fields:

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

The following query:

query-pr 500 --submitter=icabod

returns summary information for PR number 500 if and only if its ‘Submitter-Id’ field contains the value ‘mitchell’ (i.e., only if PR number 500 was submitted by mitchell.)

The following example shows another alternative output function:

query-pr --sql search criteria…

The ‘--sql’ (or ‘-i’) option prints information in a format which can be uploaded into a relational database. The output is one line per PR, delimited with pipe (‘|’) symbols, and contains the following fields in order:

id-number | category | synopsis | confidential | \
severity | priority | responsible | state | class | \
submitter-id | arrival-date | originator | release

[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2 Editing existing Problem Reports

Use edit-pr to make changes to existing PRs in the database. The shell script and Emacs Lisp file are designed to keep the data in each Problem Report and in the index consistent, and also provide an easy and safe way to edit PRs. State changes (when progress toward a solution is being made) and responsibility changes (“passing the bug”) are tracked in the ‘>Audit-Trail:’ field.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.1 edit-pr in Emacs

Call edit-pr from within Emacs with M-x edit-pr. You will be prompted for a PR identification number; type the number of the PR you wish to edit.

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

C-c C-s
gnats-submit-pr

Save and submit the PR currently being edited. Do this when you’re finished editing; if you simply kill the buffer, your changes will be lost.

C-c C-e
edit-pr

Runs edit-pr in a new buffer.

C-c C-a
gnats-mail-reply

Sends mail to the originator of this PR, using the address in the ‘From:’ field of the mail header.

C-c RET
gnats-mail-other-window

Splits the current window, and sends mail to the originator of this PR, using the address in the ‘From:’ field of the mail header, in the new window.

C-c C-r
gnats-responsible-change-from-to

Change the ‘Responsible’ field. You will be prompted for the new responsible person. Each time the ‘Responsible’ field is changed, the previous value and the reason for the change are both mailed to the responsible parties and the submitter, and recorded in the ‘Audit-Trail’ section of the PR as follows:

Responsible-Changed-<From>-<To>: Records the value change.
Responsible-Changed-By: Your name here.
Responsible-Changed-When: Records the current date.
Responsible-Changed-Why: Emacs places the point in this

field as a prompt for you to fill in the reason for the change.

C-c C-s
gnats-state-change-from-to

Change the ‘State’ field. You will be prompted for the new state. Each time the ‘State’ field is changed, the previous value and the reason for the change are both mailed to the responsible parties and the submitter, and recorded in the ‘Audit-Trail’ section of the PR as follows:

State-Changed-<From>-<To>: Records the value change.
State-Changed-By: Your name here.
State-Changed-When: Records the current date.
State-Changed-Why: Emacs places the point in this field as

a prompt for you to fill in the reason for the change.

M-C-b
gnats-backward-field

Moves the point to the beginning of the value of the current field.

M-C-f
gnats-forward-field

Moves the point to the end of the value of the current field.

M-p
gnats-previous-field

Moves the point back one field to the beginning of the value of the previous field.

M-n
gnats-next-field

Moves the point forward one field to the beginning of the value of the next field.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.2.2 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 current version number of edit-pr.

-h or --help

Prints the usage message shown above.

edit-pr first examines the value you specify for gnats-id and locks the corresponding PR 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 will tell you the name of the person who has it locked.

edit-pr then 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, you will be asked on the standard input to specify reasons for changes if you’ve changed either the ‘Responsible’ field or the ‘State’ field; the information you provide when changing either of these two fields is tracked along with the change that occurred, your name, and the time of change in a section of the PR called the ‘Audit-Trail’. Copies of the ‘Audit-Trail’ are then mailed to you, to gnats-admin, and to the person Responsible for the bug as listed in the ‘gnats-adm/responsible’ (both the new Responsible and the old one, if that value changed).


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.3 Managing GNATS

In daily usage, GNATS is self-maintaining. However, there are various administrative duties which will have to be performed periodically:

emptying the pending directory

If a Problem Report arrives with a ‘Category’ field that is unrecognized by the ‘gnats-adm/categories’ file, it is placed in the directory ‘GNATS_ROOT/pending’, as GNATS has no way of knowing which subdirectory it should be filed under. GNATS sends a notice to the gnats-admin and to the party responsible for that submitter (as listed in the ‘submitters’ file) when this occurs.

To file these PRs, simply call edit-pr on each file in the ‘pending’ directory and repair the problematic category. In many cases the culprit is simply a typographical error, although it may be necessary sometimes to contact the submitter of the PR to decipher the originator’s intentions.

adding new categories

To add a new category, simply insert a new line in the ‘categories’ file and then run the program mkcat. This automatically creates a subdirectory in GNATS_ROOT for this category, and updates the local list of known categories for send-pr. See section The categories file.

It is important to note that only your local send-pr will have access to this new information; any copies of send-pr which you have distributed will have outdated category lists. You must either contact your submitters and instruct them to update their copy of the categories list, which they installed in ‘libdir/gnats/support-site’ from the distribution you provided, or you must build another distribution of send-pr with this new information and redistribute it.

removing categories

To remove a category, you need to:

building a distribution of send-pr

After you edit your ‘categories’ file to reflect the nature of your support activities, you can build a distribution of this custom category configuration by invoking the command mkdist.

mkdist creates a ‘Makefile’ and a valid category list in a directory which you specify on the command line, which will contain a full distribution of the program send-pr, including a Makefile, an up-to-date list of categories your organization supports, and all send-pr documentation. See section Configuring send-pr for the outside world.

building a new index

If for some reason the ‘index’ becomes corrupted, or if you wish to generate a new one for some reason, use the program gen-index as follows.

gen-index [-n | --numeric] [-d dir | --directory=dir]
          [-o file | --outfile=file] [-h | --help]

With no options, gen-index generates an index that is ordered the same as the order of the categories as they appear in the ‘categories’ file. The options are:

-n
--numeric

Sort index entries numerically.

-d dir
--directory=dir

Use dir as the root directory.

-o file
--outfile=file

Place output in the file file rather than sending it to standard output.

-h
--help

Print the usage for gen-index.

removing file locks from failed editing sessions

edit-pr “locks” each file while the file is being edited. This is to ensure that no two users edit the same PR at the same time, thus avoiding data collisions. If edit-pr crashes for some reason, however, the lock remains in place, as edit-pr does not remove the lock until the new PR is in place. File locks are simply files in the database named

GNATS_ROOT/category/gnats-id.lock

where gnats-id is the PR being edited.

If a GNATS user finds a PR locked, first make sure that no one else is editing that PR (it has been known to occur that some users will background an editing session and then forget that it exists), then log in as gnats and run

gnats-bin/pr-edit --unlock gnats-id
BACKING UP YOUR DATA

Any database is only useful if its data remains uncorrupted and safe. Performing periodic backups ensures that problems like disk crashes and data corruption are reversible.

pruning log files

Log files often grow to unfathomable proportions. As with gardening, it is best to prune these as they grow, lest they take over your disk and leave you with no room to gather more bugs.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

3.4 Configuring send-pr for the outside world

Now that GNATS is up and running on your system, you probably want to distribute send-pr to all your friends, relatives, enemies, etc. so they can more easily submit bugs to your organization. To do this, log in as gnats and create a directory to hold the distribution. Then run the program

gnats-bin/mkdist dist-directory release

This creates a directory called dist-directory (you can specify a full pathname) which contains a full distribution of the program send-pr, including a ‘Makefile’ and all the send-pr documentation. You can then simply package up this directory and send it to your bug report submitters.


[ << ] [ < ] [ Up ] [ > ] [ >> ]         [Top] [Contents] [Index] [ ? ]

Index

Jump to:   -   >  
A   B   C   D   E   F   G   H   I   K   L   M   N   O   P   Q   R   S   T   U   V   W  
Index Entry  Section

-
--request-id’ option 1.5.2 Problem Report fields

>
>Arrival-Date: 1.5.2 Problem Report fields
>Audit-Trail: 1.5.2 Problem Report fields
>Category: 1.5.2 Problem Report fields
>Class: 1.5.2 Problem Report fields
>Confidential: 1.5.2 Problem Report fields
>Description: 1.5.2 Problem Report fields
>Environment: 1.5.2 Problem Report fields
>How-To-Repeat: 1.5.2 Problem Report fields
>Organization: 1.5.2 Problem Report fields
>Originator: 1.5.2 Problem Report fields
>Priority: 1.5.2 Problem Report fields
>Release: 1.5.2 Problem Report fields
>Responsible: 1.5.2 Problem Report fields
>Severity: 1.5.2 Problem Report fields
>Submitter-Id: 1.5.2 Problem Report fields
>Synopsis: 1.5.2 Problem Report fields
>Unformatted: 1.5.2 Problem Report fields

A
account for gnats-admin 2 Configuring and installing GNATS
ACKNOWLEDGE 2.3 The config.h file
adding new categories 3.3 Managing GNATS
admin files 2.4 Files used for GNATS administration
administering GNATS 3.3 Managing GNATS
alias for incoming bug reports 2 Configuring and installing GNATS
alias for your site 2 Configuring and installing GNATS
allowing cron and at commands 2 Configuring and installing GNATS
analyzed state 1.4 States of Problem Reports
appending PRs 1.2 Data Flow
Arrival-Date’ field 1.5.2 Problem Report fields
at and cron 2 Configuring and installing GNATS
at-pr 1.2 Data Flow
at.allow 2 Configuring and installing GNATS
at.deny 2 Configuring and installing GNATS
Audit-Trail’ field 1.5.2 Problem Report fields
automatic notification 1.4 States of Problem Reports

B
BACKING UP YOUR DATA 3.3 Managing GNATS
bug alias 2 Configuring and installing GNATS
building a distribution of send-pr 3.3 Managing GNATS
building a new index 3.3 Managing GNATS

C
categories 2.4.1 The categories file
Category’ field 1.5.2 Problem Report fields
change-request class bugs 1.5.2 Problem Report fields
changing the build directory 2.1.2 Changing the build directory
changing the installation location 2.1.1 Changing the installation location
Class’ field 1.5.2 Problem Report fields
closed state 1.4 States of Problem Reports
Confidential’ field 1.5.2 Problem Report fields
config.h 2.3 The config.h file
configure 2 Configuring and installing GNATS
configure 2.1 Configuring GNATS on your system
configuring and installing GNATS 2 Configuring and installing GNATS
configuring for your site 2 Configuring and installing GNATS
configuring GNATS on a network 2.2 Using GNATS over a network
configuring GNATS on your system 2.1 Configuring GNATS on your system
configuring send-pr for the outside world 3.4 Configuring send-pr for the outside world
creating an account for gnats 2 Configuring and installing GNATS
critical severity bugs 1.5.2 Problem Report fields
cron and at 2 Configuring and installing GNATS
cron.allow 2 Configuring and installing GNATS
cron.deny 2 Configuring and installing GNATS
current 2.4.5 The current file

D
data fields 1.5 GNATS data fields
data flow 1.2 Data Flow
database paradigm 1.1 The database paradigm
database rationale 1 Introducing GNATS
DEFAULT_ORGANIZATION 2 Configuring and installing GNATS
DEFAULT_RELEASE 2 Configuring and installing GNATS
DEFAULT_SUBMITTER 2.3 The config.h file
Description’ field 1.5.2 Problem Report fields
doc-bug class bugs 1.5.2 Problem Report fields
duplicate class bugs 1.5.2 Problem Report fields
duties for gnats-admin 3.3 Managing GNATS

E
edit-pr 3.2 Editing existing Problem Reports
edit-pr from the shell 3.2.2 edit-pr from the shell
edit-pr in Emacs 3.2.1 edit-pr in Emacs
editing ‘gnats/config.h 2 Configuring and installing GNATS
editing ‘gnats/Makefile.in 2 Configuring and installing GNATS
emptying the pending directory 3.3 Managing GNATS
Environment’ field 1.5.2 Problem Report fields
example queries 3.1.2 Example queries

F
feedback state 1.4 States of Problem Reports
field format 1.5.2 Problem Report fields
fields 1.5 GNATS data fields
fields - list 1.5.2 Problem Report fields
files used for GNATS administration 2.4 Files used for GNATS administration
final state (closed) 1.4 States of Problem Reports
flowchart of GNATS activities 1.3 Flowchart of GNATS activities

G
gen-index 3.3 Managing GNATS
GNATS data fields 1.5 GNATS data fields
GNATS database fields 1.5.2 Problem Report fields
GNATS fields - list 1.5.2 Problem Report fields
GNATS in action 1.2 Data Flow
GNATS management 3.3 Managing GNATS
GNATS_ADDR 2 Configuring and installing GNATS
GNATS_ROOT 2 Configuring and installing GNATS
GNATS_SITE 2 Configuring and installing GNATS

H
high priority bugs 1.5.2 Problem Report fields
how it works 1.2 Data Flow
How-To-Repeat’ field 1.5.2 Problem Report fields

I
incoming alias for bug reports 2 Configuring and installing GNATS
index 2.4.4 The index file
initial state (open) 1.4 States of Problem Reports
installation locations for user utilities 2.1.1 Changing the installation location
installing GNATS 2 Configuring and installing GNATS
Internet standard RFC-822 1.5.1 Mail Header fields
introduction to GNATS 1 Introducing GNATS
invoking edit-pr 3.2 Editing existing Problem Reports
invoking mkdist 3.4 Configuring send-pr for the outside world
invoking query-pr 3.1 Querying individual Problem Reports
invoking the GNATS tools 3 Invoking the GNATS tools

K
KEEP_RECEIVED_HEADERS 2.3 The config.h file

L
local conventions 2 Configuring and installing GNATS
log files 2 Configuring and installing GNATS
low priority bugs 1.5.2 Problem Report fields

M
mail alias for gnats-admin 2 Configuring and installing GNATS
mail alias for your site 2 Configuring and installing GNATS
mail header fields 1.5.1 Mail Header fields
maintenance 1.1 The database paradigm
make all 2 Configuring and installing GNATS
make install 2 Configuring and installing GNATS
managing GNATS 3.3 Managing GNATS
medium priority bugs 1.5.2 Problem Report fields
mistaken class bugs 1.5.2 Problem Report fields
mkcat 2 Configuring and installing GNATS
mkcat 3.3 Managing GNATS
mkdist 3.3 Managing GNATS

N
networks 2 Configuring and installing GNATS
networks 2.2 Using GNATS over a network
non-critical severity bugs 1.5.2 Problem Report fields
NOTIFY 2.3 The config.h file

O
objdir 2.1.2 Changing the build directory
open bugs 1.4 States of Problem Reports
Organization’ field 1.5.2 Problem Report fields
Originator’ field 1.5.2 Problem Report fields
other flags to configure 2.1.3 Other flags to configure
other information 1.2 Data Flow
other mail 1.2 Data Flow
overview to GNATS Overview

P
paradigm 1 Introducing GNATS
paradigm 1.1 The database paradigm
pending directory 1.2 Data Flow
prefix (configure) 2.1.1 Changing the installation location
Priority’ field 1.5.2 Problem Report fields
Problem Report data types 1.5.2 Problem Report fields
Problem Report states 1.4 States of Problem Reports
pruning log files 3.3 Managing GNATS

Q
query-pr 3.1 Querying individual Problem Reports
query-pr --sql 3.1.2 Example queries
querying invdividual problem reports 3.1 Querying individual Problem Reports
queue-pr -q 2 Configuring and installing GNATS
queue-pr -r via cron 2 Configuring and installing GNATS

R
rationale 1 Introducing GNATS
related mail 1.2 Data Flow
Release’ field 1.5.2 Problem Report fields
reminder message 1.2 Data Flow
removing categories 3.3 Managing GNATS
removing file locks from failed editing sessions 3.3 Managing GNATS
responsible 2.4.2 The responsible file
Responsible’ field 1.5.2 Problem Report fields
Responsible-Changed-<From>-<To>:’ in ‘Audit-Trail 1.5.2 Problem Report fields
Responsible-Changed-By:’ in ‘Audit-Trail 1.5.2 Problem Report fields
Responsible-Changed-When:’ in ‘Audit-Trail 1.5.2 Problem Report fields
Responsible-Changed-Why:’ in ‘Audit-Trail 1.5.2 Problem Report fields
rmcat 3.3 Managing GNATS
root priviledges 2 Configuring and installing GNATS
running configure 2 Configuring and installing GNATS
running make all 2 Configuring and installing GNATS
running make install 2 Configuring and installing GNATS
running queue-pr -r via cron 2 Configuring and installing GNATS

S
sample code 1.2 Data Flow
saving related mail 1.2 Data Flow
serious severity bugs 1.5.2 Problem Report fields
setting up GNATS 2 Configuring and installing GNATS
Severity’ field 1.5.2 Problem Report fields
site alias 2 Configuring and installing GNATS
state—analyzed 1.4 States of Problem Reports
state—closed 1.4 States of Problem Reports
state—feedback 1.4 States of Problem Reports
state—open 1.4 States of Problem Reports
state—suspended 1.4 States of Problem Reports
State-Changed-<From>-<To>:’ in ‘Audit-Trail 1.5.2 Problem Report fields
State-Changed-By:’ in ‘Audit-Trail 1.5.2 Problem Report fields
State-Changed-When:’ in ‘Audit-Trail 1.5.2 Problem Report fields
State-Changed-Why:’ in ‘Audit-Trail 1.5.2 Problem Report fields
states of Problem Reports 1.4 States of Problem Reports
Submitter-Id’ field 1.5.2 Problem Report fields
submitters 2.4.3 The submitters file
support class bugs 1.5.2 Problem Report fields
support site 1.1 The database paradigm
suspended state 1.4 States of Problem Reports
sw-bug class bugs 1.5.2 Problem Report fields
Synopsis’ field 1.5.2 Problem Report fields

T
test cases 1.2 Data Flow
the categories file 2.4.1 The categories file
the ‘config.h’ file 2.3 The config.h file
the current file 2.4.5 The current file
the index file 2.4.4 The index file
the responsible file 2.4.2 The responsible file
the submitters file 2.4.3 The submitters file
tool usage for software maintainers 3 Invoking the GNATS tools

U
Unformatted’ field 1.5.2 Problem Report fields
unpacking the distribution 2 Configuring and installing GNATS
usage for the GNATS tools 3 Invoking the GNATS tools
using edit-pr 3.2 Editing existing Problem Reports
using GNATS over a network 2.2 Using GNATS over a network
using mkdist 3.4 Configuring send-pr for the outside world
using query-pr 3.1 Querying individual Problem Reports
utility installation locations 2.1.1 Changing the installation location

V
version 3.01 Overview
visual map of data flow 1.3 Flowchart of GNATS activities

W
why GNATS? 1.1 The database paradigm

Jump to:   -   >  
A   B   C   D   E   F   G   H   I   K   L   M   N   O   P   Q   R   S   T   U   V   W  

[Top] [Contents] [Index] [ ? ]

Table of Contents


[Top] [Contents] [Index] [ ? ]

About This Document

This document was generated on May 19, 2025 using texi2html 5.0.

The buttons in the navigation panels have the following meaning:

Button Name Go to From 1.2.3 go to
[ << ] FastBack Beginning of this chapter or previous chapter 1
[ < ] Back Previous section in reading order 1.2.2
[ Up ] Up Up section 1.2
[ > ] Forward Next section in reading order 1.2.4
[ >> ] FastForward Next chapter 2
[Top] Top Cover (top) of document  
[Contents] Contents Table of contents  
[Index] Index Index  
[ ? ] About About (help)  

where the Example assumes that the current position is at Subsubsection One-Two-Three of a document of the following structure:


This document was generated on May 19, 2025 using texi2html 5.0.