3. GNATS Administration

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

emptying the pending directory

If a Problem Report arrives with a `>Category:' value that is unrecognized by the `categories' file, or if that field is missing, GNATS places the PR in the `pending' directory (see section Where the tools and utilities reside). GNATS has no way of knowing which subdirectory the PR 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 use edit-pr to repair the problematic fields in each file in the `pending' directory. Be sure to change the `>Category:' field of the PR from `pending' to an appropriate 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 her or his intentions.

Should you run out of disk space, there may be an empty PR in the `pending' directory. In that case, look in the file `GNATS_ROOT/gnats-adm/bug.log', which should still contain the full message that was submitted.

adding new categories

To add a new category, simply insert a new line in the `categories' file and then run the program mkcat.

Note: this causes all category lists for send-pr (except the one on the local machine) to become outdated. Copy the new list on to every machine on your network that has send-pr installed, and make sure you advise remote submitters that the category list has changed. See section Adding a problem category. Also The categories file.

removing categories

To remove a category, you need to make sure the relevant subdirectory is empty (in other words, make sure no PRs exist for the category you wish to remove). You can then remove the category listing from the `categories' file, and invoke

rmcat category...

to remove category (any number of categories may be specified on the command line to rmcat, so long as they abide by the above constraints).

Note: this causes all category lists for send-pr (except the one on the local machine) to become outdated. Copy the new list on to every machine on your network that has send-pr installed, and make sure you advise remote submitters that the category list has changed. See section Removing a problem category. Also The categories file.

adding and removing maintainers

Edit the `responsible' file to add a new maintainer or to remove an existing maintainer. See section The responsible file.

building a distribution of send-pr

You can build a distribution of send-pr which contains valid information for your site by invoking the command mkdist. See section Configuring send-pr for the outside world. You can then distribute your customized send-pr to your customers, friends, relatives, etc., so that they can submit Problem Reports to your database.

building a new index

If your index becomes corrupted, or if you wish to generate a new one for some reason, use the program gen-index (see section Regenerating the index).

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 Problem Reports. If you keep log files, be sure to keep an eye on them. (See section Setting up mail aliases.)

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.

See section Where GNATS lives.

3.1 Managing GNATS over a network

If you have installed the GNATS user tools on machines around your local network, there are a few things you need to remember.

mkcat and rmcat do not update the categories list for other machines on your network which have send-pr installed, unless those machines share prefix with the host machine). To update these lists, copy the send-pr categories list to each of the other hosts. This categories list is `prefix/lib/gnats/site', where site is the name tag for your local site, as specified in the `config' file as `GNATS_SITE' (see section The config file).

It is also important to note that only your local send-pr has access to this new information; any copies of send-pr which you have distributed to outside submitters now 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 `prefix/lib/gnats/support-site' from the distribution you provided, or you must build another distribution of send-pr with this new information and redistribute it.

If you need to use GNATS utilities, like query-pr and edit-pr, on other systems besides the one where GNATS itself resides, see section Installing the user tools.

3.2 Changing your local configuration

See section Where GNATS lives.

Your local configuration is determined by the data files in the directory `GNATS_ROOT/gnats-adm'. These can be altered at any time by editing the pertinent file.

config

Variables which control certain behavior. See section The config file. Behaviors you can change here include

• The address where your site receives Problem Reports.

• The address of the GNATS administrator.

• The nametag for your Support Site (your organization, company, group, etc.).

• The nametag for your local Submitter Site.

• The default release for your site.

• The default value for the `>Organization:' field (this value appears as the default when you run send-pr).

• Whether or not to remind maintainers if a requisite time period has passed before they change the state of a Problem Report to `analyzed'. (Also see The submitters file, and Timely Reminders.

• Whether or not to send an automatic acknowledgement to the originator of a problem report when the GNATS first receives the PR.

• The value GNATS assigns to PRs which come in with missing or unknown values for the `>Submitter-Id:' field.

• Whether or not GNATS should retain `Received:' mail headers from incoming mail.

• Whether or not GNATS is in a mode for debugging.

• The values which define business hours.

categories

The list of categories that GNATS accepts as valid for the `>Category:' field, and the maintainers responsible for each category. Update this file whenever you have a new category, or whenever a category is no longer valid. You must also update this file whenever responsiblility for a category changes, or if a maintainer is no longer valid. See section The categories file. Also see Adding a new problem category, and Removing a problem category.

responsible

The list of maintainers. Update this file whenever you have a new maintainer, or whenever a maintainer is no longer valid. See section The responsible file.

submitters

The list of Submitter Sites from whom GNATS accepts Problem Reports. This file is mandatory, although the feature it provides is not; see The submitters file.

3.2.1 Default behavior

The default behavior for GNATS is as follows:

• The address where your site receives Problem Reports is `bugs' (a local address).

• The address of the GNATS administrator is `gnats-admin' (a local address).

• The nametag for your Support Site (your organization, company, group, etc.) is the second-to-last field in your domain name.

• The nametag for your local Submitter Site is the nametag for your Support Site.

• The default release for your site is `unknown-1.0'.

• The default value for the `>Organization:' field (this value appears as the default when you run send-pr) is the nametag for your Support Site.

• GNATS reminds maintainers if a requisite time period has passed before they change the state of a Problem Report to `analyzed'.

• An automatic acknowledgement is sent to the originator of a problem report when the GNATS first receives the PR.

• The value GNATS assigns to the `>Submitter-Id:' field in PRs which arrive with missing or unknown values for that field is `unknown'.

• `Received...' mail headers are retained.

• GNATS is not in a debugging mode.

• business hours are defined as 8:00am to 5:00pm, Monday through Friday.

3.2.2 The config file

Much of the behavior GNATS exhibits depends on the values of fields in the file `GNATS_ROOT/gnats-adm/config'. The `config' file contains a list of variables (using Bourne-shell syntax) which control the following behavior. These values can be changed at any time; the new values take effect for all subsequent iterations of the tools.

GNATS_ADDR="address"

The address where your site receives Problem Reports. This address is aliased in the file `/etc/aliases' so that it directs incoming mail into queue-pr (see section Installing the utilities).

The default is `bugs' (a local address).

GNATS_ADMIN="address"

The address of the GNATS administrator. Normally this is set to `gnats-admin', which is an alias in `/etc/aliases' that points toward the person responsible for administrating GNATS. See section Installing the utilities.

The default is `gnats-admin' (a local address).

GNATS_SITE="site"

The nametag for your Support Site (your organization, company, group, etc.). This nametag should also appear in the `submitters' file, so that users at your site can submit Problem Reports locally.

site is also used as the name of the file containing a valid category list for your site. This file is installed locally as `prefix/lib/gnats/site'. Warning: if you change this variable after GNATS is installed, you must also change the name of this file, as well as the name of the alias for your local submitters (see section Setting up mail aliases).

The default is the second-to-last field in your domain name. For example, if your domain name is `unleaded.truckstop.org', your default site is `truckstop'.

SUBMITTER="submitter-id"

The nametag for your local Submitter Site (this value appears as the default value for `>Submitter-Id' when you run send-pr). Even though you are a Support Site, if you submit Problem Reports to your own organization you become a Submitter Site. The value submitter-id is the default value for the `>Submitter-Id:' field that your maintainers see when they submit Problem Reports locally.

The default is the value of `GNATS_SITE'.

DEFAULT_RELEASE="release"

The default release for your site (this value appears as the default value for `>Release:' when you run send-pr).

The default is `unknown-1.0'.

DEFAULT_ORGANIZATION="text"

The default value for the `>Organization:' field (this value appears as the default when you run send-pr).

The default is the value of `GNATS_SITE'.

NOTIFY=boolean

Determines whether or not to remind maintainers if a requisite time period has passed before they change the state of a Problem Report to `analyzed'. This feature uses the program at-pr; see Timely Reminders.

This requisite time is determined for each submitter individually; see The submitters file. The time is measured in business hours, which by default are 8:00am to 5:00pm, Monday through Friday. Business hours can be redefined by changing the variables BDAY_START, BDAY_END, BWEEK_START, and BWEEK_END in the `config' file (see below).

If boolean is `1', this feature is active. If boolean is `0', the feature is turned off. The default value for `NOTIFY' is `1'.

ACKNOWLEDGE=boolean

Determines whether or not to send an automatic acknowledgement to the originator of a problem report when the GNATS first receives the PR.

If boolean is `1', this feature is active. If boolean is `0', the feature is turned off. The default for `ACKNOWLEDGE' is `1'.

The acknowledgment is of the form:

To: your-address From: gnats Subject: Re: category/gnats-id:Synopsis In-Reply-To: Your message of date Thank you very much for your problem report. It has the internal identification: category/gnats-id The individual assigned to look at your bug is: responsible Category: category of the PR Responsible: responsible Synopsis: Synopsis from submitted PR Arrival-Date: arrival date

DEFAULT_SUBMITTER="submitter-id"

The value GNATS assigns to PRs which come in with missing or unknown values for the `>Submitter-Id:' field. This value must also appear in the `submitters' file; see The submitters file.

To disable the feature of GNATS which tracks the `>Submitter-Id:', simply alter the `submitters' file to only contain the submitter-id value which appears in DEFAULT_SUBMITTER, and instruct your submitters to ignore the field.

The default value for `DEFAULT_SUBMITTER' is `unknown'.

KEEP_RECEIVED_HEADERS=boolean

Determines whether or not GNATS should retain the `Received:' mail headers from incoming mail. These headers often take up a lot of space, and they are seldom used.

If boolean is `1', this feature is active. If boolean is `0', the feature is turned off. The default value for `KEEP_RECEIVED_HEADERS' is `1'.

DEBUG_MODE=boolean

Determines whether or not GNATS is operating in a mode for debugging. When boolean is `1', GNATS forwards all mail to the GNATS administrator, gnats-admin.

BDAY_START=integer

BDAY_END=integer

BWEEK_START=integer

BWEEK_END=integer

The definition of business hours. These values are only used if NOTIFY is set to `1' in the `config' file (see above).

By default, business hours are 8:00am to 5:00pm Monday through Friday, local time.

BDAY_START=integer

Defines the hour of the day when business hours begin. integer values must fall between `0' (midnight) and `23' (11:00pm). The default is `8' (8:00am).

BDAY_END=integer

Defines the hour of the day when business hours end. integer values must fall between `0' (midnight) and `23' (11:00pm). The default is `17' (5:00pm).

BWEEK_START=integer

Defines the beginning day of the business week. integer values must fall between `0' (Sunday) and `6' (Saturday). The default is `1' (Monday).

BWEEK_END=integer

Defines the ending day of the business week. integer values must fall between `0' (Sunday) and `6' (Saturday). The default is `5' (Friday).

3.2.3 The categories file

The `categories' file contains a list of problem categories, specific to your site, which GNATS tracks. This file also matches responsible people with these categories. You must edit this file initially, creating valid categories and then running mkcat to create the corresponding subdirectories of GNATS_ROOT and update the valid categories list for send-pr. 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. 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 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 (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, or perhaps with sub-categories within each category. For instance, if you wish to track documentation problems in a variety of areas, you could have entries such as

doc:General Doc Questions:myboss:me,barney
doc-rock:Doc for ROCK program:me:myboss
doc-stone:Docs for STONE utils:barney:fred
doc-local:in-house documentation:me:doc-local-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 `doc' are sent to the local mail address (or alias) `myboss', and also sent to the addresses `me' and `barney'. PRs with a category of `doc-rock' are sent to the local addresses `me' and `myboss' only, while PRs with the category `doc-stone' are sent to `fred' as well as to `barney'. PRs with a category of `doc-local' are sent only to `me', and are also filed in 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 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' (see section Configuring and compiling the software).

3.2.4 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 a mail alias, so for this purpose gnats-admin is a local address.)

3.2.5 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.

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., or it can remain blank.

resp-time

Optional quoted response time, in business hours. GNATS is capable of reminding responsible parties when Problem Reports marked with a `>Severity' value of `critical', or those with a `>Severity' of `serious' and a `>Priority' value of `high', are neglected for a certain period. This argument defines that response period for each submitter-id. Business hours are defined by default as 8:00am to 5:00pm, Monday through Friday. For example, three business days would be equal to 24 business hours.

This function is active if the NOTIFY field is defined as `1' in the `config' file (see section Changing your local configuration). If NOTIFY is `0', this field is ignored. 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.

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 the submitter-id value which appears as the `DEFAULT_SUBMITTER' value in the `config' file (see section The config file), and instruct your submitters to ignore the field.

3.3 Administrative data files

The following files are located in `GNATS_ROOT/gnats-adm', where GNATS_ROOT is the resident directory of GNATS. These files are maintained by GNATS; you should never touch them.

3.3.1 The index file

The index is used to accelerate searches on the database by query-pr and edit-pr. 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 are much faster than searches which depend on data not in the index. The index contains single-line entries for the following fields, in order, separated by colons (`:') except for `>Category:' and `>Number:', which are separated by a slash (`/') (the `>' and `:' Problem Report fieldname delimiters have been removed for the sake of brevity and readability)::

Category       Number         Submitter-Id
Responsible    State          Confidential
Severity       Priority

To see an example index, run gen-index without any options (see section Regenerating the index).

3.3.2 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.

3.4 Administrative utilities

These tools are used by the GNATS administrator as part of the periodic maintenance and configuration of GNATS. See section GNATS Administration.

3.4.1 Adding a problem category

To add new categories to the database:

1. Add a line to the `categories' file under `GNATS_ROOT/gnats-adm' for each new category. See section The categories file.

2. Run mkcat. mkcat creates a directory under GNATS_ROOT for any new categories which appear in the `categories' file. mkcat also recreates the list of valid categories for both your locally installed send-pr and for the send-pr distribution template in `prefix/lib/gnats/dist' (see section Where GNATS lives.

Note: mkcat does not update the categories list for other machines on your network which have send-pr installed (unless the two machines share the directory prefix). See section Managing GNATS over a network.

It is also important to note that only your local send-pr has access to this new information; any copies of send-pr which you have distributed to outside submitters now 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 `prefix/lib/gnats/support-site' (Note: the value for prefix may be different from yours) from the distribution you provided, or you must build another distribution of send-pr with this new information and redistribute it (see section Configuring send-pr for the outside world).

3.4.2 Removing a problem category

To remove a category from the database:

1. Remove the Problem Reports from the subdirectories corresponding to the categories you wish to remove, or assign the PRs to new categories. All PRs for a given category reside in `GNATS_ROOT/category'. Make sure you do this for each category you wish to remove.

2. Run rmcat using

   rmcat category [ category... ]

   where category is the category you wish to remove. You can specify as many categories as you wish as long as each category has no PRs associated with it. rmcat removes the directory under GNATS_ROOT where the Problem Reports for that category had been stored. rmcat also deletes the category from the list of valid categories for both your locally installed send-pr and for the send-pr distribution template in `prefix/lib/gnats/dist' (see section Where GNATS lives).

Note: rmcat does not update the categories list for other machines on your network which have send-pr installed. See section Managing GNATS over a network.

It is also important to note that only your local send-pr has access to this new information; any copies of send-pr which you have distributed to outside submitters now 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 `prefix/lib/gnats/support-site' (Note: the value for prefix may be different from yours) from the distribution you provided, or you must build another distribution of send-pr with this new information and redistribute it (see section Configuring send-pr for the outside world).

3.4.3 Regenerating the index

If your `index' file becomes corrupted, or if you need a copy of the current index for some reason, use

gen-index [ -n | --numeric ]
          [ -d directory | --directory=directory ]
	  [ -c filename | --catfile=filename ]
          [ -o filename | --outfile=filename ]
          [ -h | --help] [ -V | --version ]

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, and prints it to standard output. The options are:

-n

--numeric

Sorts index entries numerically.

-d directory

--directory=directory

Uses directory as the directory containing the database, by default GNATS_ROOT (see section Where GNATS lives).

-o filename

--outfile=filename

Places output in filename rather than sending it to standard output.

-c filename

--catfile=filename

Point to filename, the file listing the valid categories.

-h

--help

Prints the usage for gen-index.

-V

--version

Prints the version number for gen-index.

3.4.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, create a new directory dist-directory to hold the distribution. Then run the program

mkdist --release=release dist-directory

This populates dist-directory with 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. For example, when logged in as gnats you can do the following:

mkdir new-dist
mkdist --release=tools-1.2 new-dist 
tar cvf send-pr.tar new-dist

This creates a file called `send-pr.tar' which contains a full distribution of send-pr customized for your site, with a default release number of `tools-1.2'. You can then place this onto a disk or tape and send it to your submitters, or instruct your submitters to download it using ftp.

If you only have one submitter, you can set the Submitter ID in the send-pr script by specifying the --submitter option to mkdist. If you do this, the submitter will not have to run install-sid.

3.5 Internal utilities

These tools are used internally by GNATS. You should never need to run these by hand; however, a complete understanding may help you locate problems with the GNATS tools or with your local implementation.

3.5.1 Handling incoming traffic

The program queue-pr handles traffic coming into GNATS. queue-pr queues incoming Problem Reports in the directory `GNATS_ROOT/gnats-queue', and then periodically (via cron) passes them on to file-pr to be filed in the GNATS database. See section Installing GNATS.

The usage for queue-pr is as follows:

queue-pr [ -q | --queue ] [ -r | --run ]
         [ -f filename | --file=filename ]
         [ -d directory | --directory=directory ]

One of `-q' or `-r' (or their longer-named counterparts) must be present upon each call to queue-pr. These options provide different functions, as described below.

-q

--queue

Accepts standard input as an incoming mail message, placing this message in an incrementally numbered file in the `gnats-queue' directory under GNATS_ROOT (see section Where GNATS lives).

-r

--run

Redirects files in the `gnats-queue' directory into the program file-pr one by one.

-f filename

--file=filename

Used with `-q' (or `--queue'), accepts the file denoted by filename as input rather than reading from standard input.

-d directory

--directory=directory

Resets the default directory value, which is by default `GNATS_ROOT/gnats-queue'. When `-d directory' is used in conjunction with the `-q' (or `--queue') option, queue-pr files incoming messages into directory rather than the `gnats-queue' directory. When `-d directory' is used in conjunction with the `-r' (or `--run') option, queue-pr redirects into file-pr files from directory rather than from the `gnats-queue' directory.

3.5.2 Processing incoming traffic

queue-pr hands off queued Problem Reports to file-pr one at a time. file-pr checks each Problem Report for correct information in its fields (particularly a correct `>Category:'), assigns it an identification number, and files it in the database under the appropriate category.

If the `>Category:' field does not contain a valid category value (i.e., matching a line in the categories file; see section The categories file), the PR is given a `>Category:' value of `pending' and is placed in the `pending' directory. The GNATS administrator is notified of the unplaceable PR.

file-pr assigns the Problem Report an identification number, files it in the GNATS database (under `pending', if the `>Category:' field contains an invalid category), and sends acknowledgements to appropriate parties. The person responsible for that category of problem (see section The categories file) and the person responsible for the submitter site where the PR originated (see section The submitters file) receive a copy of the PR in its entirety. Optionally, the originator of the PR receives an acknowledgement that the PR arrived and was filed (see section Changing your local configuration).

The usage for file-pr is as follows:

file-pr [ -f filename | --file=filename ]
        [ -d directory | --directory=directoryb ]
	[ -D | --debug ] [ -h | --help ] [ -V | --version ]

file-pr requires no options in order to operate, and takes input from standard input (normally, the output of `queue-pr -r') unless otherwise specified. The options include:

-f filename

--filename=filename

Uses filename as input rather than standard input.

-d directory

--directory=directory

Performs refiling operations in directory rather than in GNATS_ROOT.

-D

--debug

Give debugging output while file-pr is running.

-h

--help

Prints the usage for file-pr.

-V

--version

Prints the version number for file-pr.

3.5.3 Timely reminders

at-pr creates a queued job using at which, after an allotted response time is past, checks the PR to see if its state has changed from `open'.

The `submitters' file contains the response time for each >Submitter-Id: (see section The submitters file). The time is determined in business hours, which are defined by default as 8:00am to 5:00pm Monday through Friday, local time. These hours are defined in the `config' file (see section The config file).

If the PR is still open after the requisite time period has passed, at-pr sends a reminder to the GNATS administrator, to the maintainer responsible for that submitter, and to the maintainer responsible for the PR with the following message:

To: submitter-contact responsible gnats-admin
Subject: PR gnats-id not analyzed in #hours hours

PR gnats-id 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 Management System (GNATS)

3.5.4 The edit-pr driver

pr-edit does the background work for edit-pr, including error-checking and refiling newly edited Problem Reports and handling file locks. It can be called interactively, though it has no useable editing interface.

The usage for pr-edit is:

pr-edit [ -l maintainer --lock=maintainer ]
        [ -u | --unlock ] [ -c | --check ] [ -F ]
	[ -L | --lockdb ] [ -U | --unlockdb ]
        [ -f filename | --filename=filename ]
        [ -d directory | --directory=directory ]
        [ -h | --help ] [ -V | --version ]
        [ gnats-id ]

A lock is placed on a Problem Report while the PR is being edited. The lock is simply a file in the same directory as the PR, with the name `gnats-id.lock', which contains the name of the maintainer who created the lock. maintainer then "owns" the lock, and must remove it before the PR can be locked again, even by the same maintainer(4). If a PR is already locked when you attempt to edit it, pr-edit prints an error message giving the name of the maintainer who is currently editing the PR.

If you do not specify gnats-id, pr-edit reads from standard input. You must specify gnats-id for the functions which affect PR locks, `--lock=maintainer' and `--unlock'.

-l maintainer

--lock=maintainer

Locks Problem Report gnats-id, failing (and returning an error message) if gnats-id is already locked, or if gnats-id does not exist. pr-edit requires that you specify gnats-id when using this option.

-u

--unlock

Unlocks Problem Report gnats-id. pr-edit requires that you specify gnats-id when using this option. You must own a file lock to remove it.

-L

--lockdb

Locks the GNATS database as a whole. This will prevent any modification to any part of the system while it's locked.

-U

--unlockdb

Unlocks the GNATS database as a whole, allowing modification of its files.

-c

--check

Checks the Problem Report in gnats-id (or standard input, if gnats-id is not present) for correct information in its ENUMERATED fields. pr-edit complains about any bogus information in the Problem Report.

-F

Forces the PR to be submitted to the database, even if there is no current index entry for it (i.e., even if the PR did not exist in the database previously).

Warning: using this option may corrupt your index. If you use it, be sure you know what you are doing.

-f filename

--filename=filename

Reads filename rather than standard input.

-d directory

--directory=directory

Resets the operating directory (GNATS_ROOT).

-h

--help

Prints the usage for pr-edit.

-V

--version

Prints the version number for pr-edit.

3.5.5 Address retrieval

Returns an electronic mail address when given a valid nametag, as it appears in the `responsible' file (see section The responsible file). If nametag is not valid, pr-addr will tell the user that it could not find the requested address.

Usage is simply:

pr-addr name

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.