1. General Questions

1.1 What is GNATS?		A very short overview
1.2 How is "GNATS" pronounced?		Pronunciation: with or without the "G"?
1.3 Where do I get it?		Where to get GNATS
1.4 What is the latest version?		Which versions are available?
1.5 Is there a Mailing List?		E-mail discussion lists
1.6 How do I Report a Bug?		How to report a bug
1.7 Upgrading Considerations		Considerations for the 3.x to 4.0 transition

1.1 What is GNATS?

GNATS is the GNU problem report management system. Problem report management systems are also known as "bug-tracking systems", though the entries need not be bugs (e.g., think of change requests). The acronym stands for "GNats: A Tracking System".

GNATS stores all information about the problem reports at a central site, and enables users to access this site by various means, including e-mail, WWW, and a network daemon. New problem reports can be created, and existing reports can be queried and updated, by most of these means.

GNATS is widely customizable: Of course you can define report categories (is the report about tool A or service B?), responsibles (who takes care of this report?), and submitters (is it from customer1 or from the sales department?). You can also define possible states of a report (open, analyzed, closed, etc.) and classes (software bug, documentation bug, change request, ...).

Starting with GNATS 4.0, you can define your own custom fields, and customize many of the built-in fields; you can have fields automatically set to a certain value when another field changes its contents (e.g., set a "Closed-Date" field to the current date when the report goes to state "closed", and unset it when it goes back from "closed" to something else), or when the report is changed at all (e.g., to maintain a "Last-Modified" field).

1.1.1 How it Works--User's View		Short overview for users
1.1.2 How it Works--Administrator's View		Short overview for system administrators

1.1.1 How it Works--User's View

Users enter their problem reports (PRs) via some front-end. This front-end either directly contacts the GNATS server, or sends the report via e-mail. (The server is available since about version 3.90 of GNATS). For an incomplete list of front-ends see 4. Client Software.

Some front-ends (like TkGnats, see 4.2 TkGnats) are capable of contacting several GNATS servers, or several problem report databases managed by the same GNATS server.

1.1.2 How it Works--Administrator's View

The server is started by a super-server like inetd or xinetd. It has a built-in access control mechanism based on IP addresses and username/password.

For users sending their PRs via e-mail, some mail addresses must be configured.

1.2 How is "GNATS" pronounced?

Q: So, How can I pronounce "GNATS?" Should I pronounce "G"?

It has been reported that the original developers pronounced the "G". (This is unlike the little insect called "gnat" where the "G" is not pronounced.)

1.3 Where do I get it?

See the GNATS home page at http://www.gnu.org/software/gnats/.

The current development version is available via CVS only, see the GNU savannah GNATS project page for the instructions how to get it.

1.4 What is the latest version?

The version numbers of GNATS 3.x is somewhat confusing, because 3.1xx is newer than 3.2.

Version 3.2 was released in 1993 (I never tried it, but it is said to be "really broken"). A lot of new features have been added since 3.2, including multiple database support and customized fields. Among the contributed software are comprehensive WWW and Tk based front-ends.

The latest 3.x release is 3.113.1. It is deprecated due to security concerns and lack of maintenance.

GNATS 4.0 was released in August 2003. It is available for download at http://ftp.gnu.org/pub/gnu/gnats/.

1.5 Is there a Mailing List?

Currently, the following GNATS mailing lists exist:

• info-gnats@gnu.org This is a low volume moderated mailing lists for GNATS related announcements, like new releases or important information.

• help-gnats@gnu.org A low-to-middle volume mailing list where anything related to GNATS can be discussed (development, help, questions, suggestions, etc.).

• bug-gnats@gnu.org Bug reports can be sent there. Please note that it's preferred to submit bug reports via the bug tracking system (see section 1.6 How do I Report a Bug?), which automatically mirrors them to this list.

Lists that are of interest mainly for the GNATS developers:

• gnats-prs@gnu.org Copies of the bug tracking system messages are sent there. Contrast to bug-gnats@gnu.org which only gets new bug reports, this list also gets the follow-ups (Whatever goes into GNATS' >Audit-Trail: field).

• gnats-commit@gnu.org CVS commit messages are sent there.

• gnats-diffs@gnu.org Diffs of committed files are sent automatically to this address.

1.6 How do I Report a Bug?

Before reporting a bug, make sure it really is a bug, not a simple misunderstanding or a misconfiguration. Please check the manual and this FAQ. You may also ask for help on the help-gnats@gnu.org mailing list.

If it is a bug, please report it via the bug tracking system. It resides at http://bugs.gnu.org/cgi-bin/gnatsweb.pl?database=gnats. This is a common bug database for GNATS, Gnatsweb and TkGnats. (And, yes, of course: It uses GNATS and Gnatsweb.)

When you report problems concerning GNATS itself, please do not forget to provide especially the following information:

• The GNATS version you are using. If your problem involves Gnatsweb or TkGnats, please also report their versions.

• The exact way how to reproduce the bug.

• Your configuration.

• If you encounter a compilation or build problem, it is especially important to mention the operating system, compiler and possibly other build utilities you use.

Providing this information in the initial report avoids further unnecessary communication, saves the limited resources of the developers (keep in mind that they are working on GNATS and friends in their spare time) and helps to track down and fix the problem soon.

1.7 Upgrading Considerations

See section `Upgrading from older versions' in Keeping Track for the upgrade process from 3.x to 4.x.

If you are running a 3.x version, please consider upgrading to 4.0. There are some security concerns about the 3.1xx code that have gone with 4.0. Furthermore, the GNATS 3 branch is not maintained anymore due to lack of capacity.

The default format of the reports has not changed during the transition from 3.113.1 to 4.0, though you may add more fields to 4.0 reports (and leave out others). The format of the index file is now binary.

However, you have to change the e-mail aliases because the meaning of the `-d' option to the client programs has changed: It took the directory of the GNATS database in 3.1xx, and now takes its name (plus, it is now installed into the `libexec' directory instead of the `lib' directory). I.e., you must change the aliases:

# GNATS 3 aliases: ourdb-query: "|/usr/local/lib/gnats/mail-query -d /usr/local/gnats/db2" ourdb-bugs: "|/usr/local/lib/gnats/queue-pr -d /usr/local/gnats/db2 -q"

to

# GNATS 4 aliases: ourdb-query: "|/usr/local/libexec/gnats/mail-query -d ourdb" ourdb-bugs: "|/usr/local/libexec/gnats/queue-pr -d ourdb -q"

Also note that the client/server protocol has changed from 3.1xx to 4.0; you cannot run clients from one version with the server from the other version.