Next: , Up: Introduction

1.1 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 acknowledgment 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. 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. 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.

Other interfaces to gnats include Gnatsweb, a web-based tool which provides features for submitting and editing PRs and querying the database, and TkGnats, a Tcl/Tk-based frontend. These tools are distributed together with gnats.

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 initially 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 Overview of gnats configuration.

gnats does not have the ability to decipher random text. If there is no default category set, 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 type is open (see States of Problem Reports). An acknowledgment may be sent to the originator of the bug report (depending on whether this feature has been switched on in the gnats configuration). 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.

When a problem has been identified, the maintainer can change its state to analyzed, and then to feedback when a solution is found. gnats may be configured so that 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 the standard states, see States of Problem Reports.)

It should be emphasized that what we describe here is the default way that gnats works, but as of version 4, gnats is extremely customizable, allowing sites to tailor almost every aspect of its behavior. See for instance The dbconfig file and See States of Problem Reports.)