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.
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 when editing problem
reports in the database.
query-pr to
make inquiries about individual PRs or groups of PRs.
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.)