2.3 Editing existing Problem Reports

Use edit-pr to make changes to existing PRs in the database. This tool can be invoked both from a shell prompt or from within GNU Emacs using ‘M-x edit-pr’.

edit-pr first examines the PR you wish to edit and locks it if it is not already locked. This is to prevent you from editing a PR at the same time as another user. If the PR you wish to edit is already in the process of being edited, edit-pr tells you the name of the person who owns the lock.

You may edit any non-readonly fields in the database. We recommend that you avoid deleting any information in the TEXT and MULTITEXT fields (such as Description and How-To-Repeat (see section Problem Report format). We also recommend that you record the final solution to the problem in the Fix field for future reference. Note that heavily customized installations of GNATS may have differently named fields, and sites using such installations should provide their own set of routines and instructions regarding how PRs should be treated throughout their life span.

After the PR has been edited, it is then resubmitted to the database, and the index is updated (see section The index file). For information on pr-edit, the main driver for edit-pr, see Internal utilities.

If you change a field that requires a reason for the change, such as the Responsible or State fields in the default configuration, edit-pr prompts you to supply a reason for the change. A message is then appended to the Audit-Trail field of the PR with the changed values and the change reason.

Depending on how the database is configured, editing various fields in the PR may also cause mail to be sent concerning these changes. In the default configuration, any fields that generate ‘Audit-Trail’ entries will also cause a copy of the new ‘Audit-Trail’ message to be sent.

Mail received at the PR submission email address and recognized by GNATS as relating to an existing PR is also appended to the ‘Audit-Trail’ field, see Following up via direct email.

2.3.1 Invoking edit-pr from the shell

The usage for edit-pr is:

edit-pr [ -V | --version ] [ -h | --help ]
        [-d database | --database database] PR Number

Network-mode-only options:

         [--host host | -H host] [--port port]
         [--user user | -v user]
         [--passwd passwd | -w passwd]

The options have the following meaning:

-h, --help

Prints a brief usage message for edit-pr.

-V, --version

Prints the version number for edit-pr.

-d database, --database database

Specifies the database containing the PR to be edited; if no database is specified, the database named ‘default’ is assumed. This option overrides the database specified in the GNATSDB environment variable.

--host host, -H host

Specifies the hostname of the gnatsd server to communicate with. This overrides the value in the GNATSDB environment variable.

--port port

Specifies the port number of the gnatsd server to communicate with. This overrides the value in the GNATSDB environment variable.

--user user, -v user

Specifies the username to login with when connecting to the gnatsd server. This overrides the value in the GNATSDB environment variable.

--passwd passwd, -w passwd

Specifies the password to login with when connecting to the gnatsd server. This overrides the value in the GNATSDB environment variable.

edit-pr calls the editor specified in your environment variable EDITOR on a temporary copy of that PR. (If you don’t have the variable EDITOR defined in your environment, the default editor vi is used.)

Edit the PR, changing any relevant fields or adding to existing information. When you exit the editor, edit-pr prompts you on standard input for a reason if you have changed a field that requires specifying a reason for the change.

2.3.2 Following up via direct email

If you have some additional information for a PR and for some reason do not want to (or cannot) edit the PR directly, you may append the information to the Audit-Trail field by mailing it to the PR submission address.

In order for GNATS to be able to recognize the mail as pertaining to an existing PR (as opposed to a new PR, see Submitting a Problem Report via direct e-mail), the Subject mail header field must contain a reference to the PR. GNATS matches the Subject header against the regular expression

\<(PR[ \t#/]?|[-[:alnum:]+.]+/)[0-9]+

to determine whether such a reference is present. Any text may precede or follow the reference in the Subject header. If more than one reference is present, the first is used and the rest ignored.

A PR reference matching the regular expression above has two parts. The second is the PR number (one or more digits). The first is either the capital letters ’PR’ optionally followed by a separator character (blank, tab, hash mark or forward slash) or the category name followed by a forward slash. Following are some examples which match the regular expression:

PR 123 PR4567 PR#890 gnats/4711

The PR number and the category (if present) are checked for existence, and if the outcome is positive, the mail is appended to the Audit-Trail field of the PR. Note that the PR need not belong to the category because PRs may move between categories.

Outgoing emails sent by GNATS itself may be configured to have a Subject header field that refers to the PR in question:

Subject: Re: PR category/gnats-id: original message subject

This makes it extremely easy to follow up on a PR by replying to such an email, see The dbconfig file and the sample, default dbconfig file installed by mkdb.

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