4.4 Other database-specific config files

4.4.1 The categories file

The ‘categories’ file contains a list of problem categories, specific to the database, which GNATS tracks. This file also matches responsible people with these categories. You must edit this file initially, creating valid categories. In most installations, GNATS is configured to create directories on disk for valid categories automatically as needed (see section Overall database configuration). If GNATS isn’t set up to do this, you need to run mkcat to create the corresponding subdirectories of the database directory. For instructions on running mkcat, see Adding a problem category.

To create a new category, log in as GNATS, add a line to this file, and run mkcat if applicable. Lines beginning with ‘#’ are ignored.

A line in the ‘categories’ file consists of four fields delimited by colons, as follows:

category:description:responsible:notify

category

A unique category name, made up of text characters. This name cannot contain spaces or any of the following characters:

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

Ideally, category names should not contain commas or begin with periods. Each line has a corresponding subdirectory in the database directory.

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 (see section The responsible file).

notify

One or more other parties which should be notified when a Problem Report 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.

rock:ROCK program:me:myboss,fred
stone:STONE utils:barney:fred
iron:IRON firewall:me:firewall-log

In the above example, the nametags ‘myboss’, ‘me’, ‘fred’, and ‘barney’ must be defined in the ‘responsible’ file (see section The responsible file).

Problem Reports with a category of ‘rock’ are sent to the local mail address (or alias) ‘me’, and also sent to the addresses ‘myboss’ and ‘fred’. PRs with a category of ‘stone’ are sent to the local addresses ‘barney’ and ‘fred’ only, while PRs with the category ‘iron’ are sent only to ‘me’, and are also filed in firewall-log (in this case, a mail alias should be set up, see section Setting up mail aliases.

If you want to separate PRs in each problem category into specific subsets, say documentation and software bugs, using the ‘classes’ file is recommended. See section The ‘classes’ file.

Only one category must be present for GNATS to function:

pending:Non-categorized PRs:gnats-admin:

The ‘pending’ directory is created automatically when you run mkdb to initialize a new database. (see section Configuring and compiling the software).

4.4.2 The responsible file

This file contains a list of the responsible parties. Lines beginning with ‘#’ are 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 is listed in the PR in the Responsible field.

full-name

The full name of the party (“Charlotte Bronte”; “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:

gnats-admin is usually defined as a mail alias when GNATS is installed, so for this purpose gnats-admin is a local address. However, this line can alos be used to redefine the email address of the GNATS administrator, by adding the desired address at the end of the line.

4.4.3 The submitters file

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

Entries are of the format:

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

submitter-id

A unique identifier for a specific site or other entity who submits Problem Reports. The first submitter-id listed in the file will be the default for PRs that arrive with invalid or empty submitter fields.

name

The full name or a description of this entity.

type

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

resp-time

Optional quoted response time in business hours. If the database ‘dbconfig’ file has the notify-about-expired-prs entry set to true (see section Overall database configuration, GNATS will use this field to schedule when it should notify the gnats-admin, responsible person and submitter contact that the PR wasn’t analyzed within the agreed response time. Business hours and business-week days are set in the ‘dbconfig’ file. For information on at-pr, the program which sends out this reminder, see Timely Reminders.

contact

The name tag of the main contact at the Support Site for this submitter. This contact should be in the ‘responsible’ file (see section The responsible file). Incoming bugs from submitter are sent to this contact. Optionally, this field can be left blank.

notify

Any other parties who should receive copies of Problem Reports sent in by submitter. They need not be listed in the ‘responsible’ file.

A few example entries in the ‘submitters’ file:

univ-hell:University of Hades:eternal: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 (who has an eternal contract), it should have ‘univ-hell’ in its Submitter-Id field. This Problem Report goes to beelzebub (who should be in the ‘responsible’ file), and if it is not analyzed within three business hours a reminder message is 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 business hours to return an analysis before a reminder is sent.

To disable the feature of GNATS which tracks the Submitter-Id, simply alter the ‘submitters’ file to only contain one submitter-id value, and instruct your submitters to ignore the field.

4.4.4 The states file

This file lists the possible states for Problem Reports. Each entry has up to three fields, separated by colons. Lines beginning with ‘#’ will be ignored.

state:type:description

state

The name of the state. It may contain alphanumerics as well as ‘-’ (hyphen), ‘_’ (underscore), or ‘.’ (period), but no other characters.

type

This is the type of the state. This field is optional and it may contain alphanumerics as well as ‘-’ (hyphen), ‘_’ (underscore), or ‘.’ (period), but no other characters.

The concept of the type of a state recognizes that there may for instance be several possible states for a Problem Report which effectively means that the PR is closed and that there may be certain actions that need to be taken when a PR reaches a “closed state”. The problem may have been resolved, it might have been decided that the problem is unsolvable or simply that it won’t be solved. Some organizations may for instance wish to consider the “suspended” state as a state of type “closed”.

Currently, the only defined state types are “open” and “closed”, the “open” type isn’t currently used for anything while the “closed” type is only used to control the Closed-Date field of PRs. Changing the state of a PR to any state of type “closed” will set the Closed-Date field with a time stamp and changing the state of a PR from one “closed” state to another will leave the Closed-Date field as it was. Changing the state of a PR from any state of type “closed” to a non-closed state will clear the Closed-Date field.

The --skip-closed option of query-pr refers to all states of type “closed”, not to a specific state name of “closed”.

description

This is is an optional one-line description of what the state means. Any character is okay in the description; a newline ends it. GNATS itself does not currently use the description for anything, but certain external tools (such as TkGnats and Gnatsweb) look for it, so it’s a good idea to include one for every state.

The first state listed will be the state automatically assigned to Problem Reports when they arrive; by default this is named “open”. The last state listed is the end state for Problem Reports — one should usually assume that a PR in this state is not being actively worked on; by default this state is named “closed”. Even if a different name has been chosen for this state, GNATS will force this state to be of type “closed”.

It is recommended that you keep the default names of “open” and “closed” for the first and last states respectively, since there may be external tools that depend on these names.

4.4.5 The addresses file

This file contains mappings between submitter IDs and corresponding e-mail addresses.

When a PR comes in without a submitter ID (if someone sends unformatted e-mail to the PR submission email address), GNATS will try to derive the submitter ID from the address in the "From:" header. The entries in this file consist of two fields, separated by a colon:

submitter-id:address-fragment

submitter-id

A valid submitter ID

address-fragment

Part of, or all of the e-mail address to be matched

Here is an example of an addresses file:

# Addresses for Yoyodine Inc
yoyodine:yoyodine.com
yoyodine:yoyodine.co.uk
# Addresses for Foobar Inc.
foobar1:sales.foobar.com
foobar2:admin.foobar.com
foobar3:clark@research.foobar.com

GNATS checks each line in the addresses file, comparing address-fragment to the end of the "From:" header, until it finds a match. If no match is found, GNATS uses the default submitter ID.

You can only have one address fragment per line, but you can have more than one line for a given submitter ID. An address fragment can be a domain (i.e. yoyodine.com), a machine location (admin.foobar.com), or a full e-mail address (clark@research.foobar.com).

GNATS can match addresses in three e-mail formats:

‘From: name@address.com’

The address by itself without a full name, not enclosed in brackets

‘From: Real Person <name@address.com>’

A full name (optional, with or without quotation marks), followed by the address enclosed in angle brackets

‘From: name@address.com (Real Person)’

An address, followed by a name or comment in parentheses

If GNATS sees other e-mail address formats, it uses the default submitter ID.

4.4.6 The classes file

This file lists the possible classes of Problem Reports. Each line consists of a class name, followed by a colon and an optional class type name (the class type name is not used for anything in the current implementation of GNATS, so it may be left blank. The class and class-type-name fields may only contain alphanumerics, ‘-’, ‘_’, and ‘.’, but no other characters.

Then comes another colon, followed by an optional one-line description of the class. GNATS itself does not use the class description, but external tools such as Gnatsweb and TkGnats may use it. Therefore, a line in this file should at least contain the following:

class::class description

Lines beginning with ‘#’ will be ignored, and the first listed class is the default class for an incoming Problem Report.

This document was generated by Chad Walstrom on March 3, 2015 using texi2html 1.82.