2. The GNATS User Tools

This chapter describes the user tools distributed with GNATS. The
GNATS administrative and internal tools tools are described in
GNATS Administration. The user tools provide
facilities for initial submission, querying and editing of Problem
Reports:

send-pr

Used by anyone who has a problem with a body of work to submit a report
of the problem to the maintainers of that work
(see section Submitting Problem Reports).

2.2.1 Creating new Problem Reports

Invoking send-pr presents a PR template with a number of
fields already filled in. Complete the template as thoroughly as
possible to make a useful bug report. Submit only one bug with each PR.

A template consists of three sections:

Comments

The top several lines of a blank template consist of a series of
comments that provide some basic instructions for completing the Problem
Report, as well as a list of valid entries for the `>Category:'
field. These comments are all preceded by the string `SEND-PR:'
and are erased automatically when the PR is submitted. The
instructional comments within `<' and `>' are also removed.
(Only these comments are removed; lines you provide that happen to have
those characters in them, such as examples of shell-level redirection,
are not affected.)

These are the informational fields that GNATS uses to route your
Problem Report to the responsible party for further action. They should
be filled out as completely as possible. (See section Problem Report format. Also see Helpful hints.)

The default template contains your preconfigured `>Submitter-Id:'.
send-pr attempts to determine values for the `>Originator:'
and `>Organization:' fields (see section Problem Report format). send-pr will set the `>Originator:' field to
the value of the NAME environment variable if it has been set;
similarly, `>Organization:' will be set to the value of ORGANIZATION.
send-pr also attempts to find out some information
about your system and architecture, and places this information in the
`>Environment:' field if it finds any.

You may submit problem reports to different Support Sites from the
default site by specifying the alternate site when you invoke
send-pr. See section 2.2.3 Invoking send-pr from the shell.
Each site has its own list of categories for
which it accepts Problem Reports.

send-pr also provides the mail header section of the template
with default values in the `To:', `From:', and
`Reply-To:' fields. The `Subject:' field is empty.

The template begins with a comment section:

SEND-PR: -*- send-pr -*-
SEND-PR: Lines starting with `SEND-PR' will be removed
SEND-PR: automatically as well as all comments (the text
SEND-PR: below enclosed in `<' and `>').
SEND-PR:
SEND-PR: Please consult the document `Reporting Problems
SEND-PR: Using send-pr' if you are not sure how to fill out
SEND-PR: a problem report.
SEND-PR:
SEND-PR: Choose from the following categories:

and also contains a list of valid >Category: values for the
Support Site to whom you are submitting this Problem Report. One (and
only one) of these values should be placed in the >Category:
field.

The mail header is just below the comment section. Fill out the
`Subject:' field, if it is not already completed using the value of
`>Synopsis:'. The other mail header fields contain default values.

where support-site is an alias on your local machine for the
Support Site you wish to submit this PR to.

The rest of the template contains GNATS fields. Each field is
either automatically completed with valid information (such as your
`>Submitter-Id:') or contains a one-line instruction specifying the
information that field requires in order to be correct. For example,
the `>Confidential:' field expects a value of `yes' or
`no', and the answer must fit on one line; similarly, the
`>Synopsis:' field expects a short synopsis of the problem, which
must also fit on one line. Fill out the fields as completely as
possible. See section Helpful hints, for suggestions as to
what kinds of information to include.

In this example, words in italics are filled in with
pre-configured information:

When you finish editing the Problem Report, send-pr mails it to
the address named in the `To:' field in the mail header.
send-pr checks that the complete form contains a valid
`>Category:'.

If your PR has an invalid value in one of the ENUMERATED fields
(see section Problem Report format), send-pr places the PR in
a temporary file named `/tmp/pbadnnnn' on your machine.
nnnn is the process identification number given to your current
send-pr session. If you are running send-pr from the
shell, you are prompted as to whether or not you wish to try editing the
same Problem Report again. If you are running send-pr from
Emacs, the Problem Report is placed in the buffer
`*gnats-send*'; you can edit this file and then submit it
with C-c C-c.

Any further mail concerning this Problem Report should be carbon-copied
to the GNATS mailing address as well, with the category and
identification number in the `Subject:' line of the message.

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

Messages which arrive with `Subject:' lines of this form are
automatically appended to the Problem Report in the `>Audit-Trail:'
field in the order received.

2.2.2 Using send-pr from within Emacs

You can use an interactive send-pr interface from within GNU
Emacs to fill out your Problem Report. We recommend that you
familiarize yourself with Emacs before using this feature
(see section `Introduction' in GNU Emacs).

Call send-pr with `M-x send-pr'.(1)send-pr responds with a
Problem Report template preconfigured for the Support Site to which
you are going to send the report.

You may also submit problem reports to different Support Sites from the
default site. To use this feature, invoke send-pr with

C-u M-x send-pr

send-pr prompts you for the name of a site. site is
an alias on your local machine which points to an alternate Support
Site. The Emacs interface to GNATS is described in a separate
section, See section 2.5 The Emacs interface to GNATS.

2.2.3 Invoking send-pr from the shell

site is an alias on your local machine which points to an address
used by a Support Site. If this argument is not present, the default
site is usually the site which you received send-pr from,
or your local site if you use GNATS locally.

Invoking send-pr with no options calls the editor named in your
environment variable EDITOR on a default PR template. If the
environment variable PR_FORM is set, its value is used as a file
name which contains a valid template. If PR_FORM points to a
missing or unreadable file, or if the file is empty, send-pr
generates an error message and opens the editor on a default template.

-f problem-report

--file problem-report

Specifies a file, problem-report, where a completed Problem Report
already exists. send-pr sends the contents of the file without
invoking an editor. If problem-report is `-',
send-pr reads from standard input.

-t mail-address

--to mail-address

Sends the PR to mail-address. The default is preset when
send-pr is configured. This option is not recommended;
instead, use the argument site on the command line.

-c mail-address

--cc mail-address

Places mail-address in the Cc: header field of the message
to be sent.

--request-id

Sends a request for a >Submitter-Id: to the Support Site.

-L

--list

Prints the list of valid >Category: values on standard output.
No mail is sent.

-s severity

--severity severity

Sets the initial value of the >Severity: field to severity.

-P

--print

Displays the PR template. If the variable PR_FORM is set in your
environment, the file it specifies is printed. If PR_FORM is not
set, send-pr prints the standard blank form. If the file
specified by PR_FORM doesn't exist, send-pr displays an
error message. No mail is sent.

-V

--version

Displays the send-pr version number and a usage summary. No mail
is sent.

2.2.4 Submitting a Problem Report via direct e-mail

In addition to using send-pr, there is another way to submit a problem
report. You can simply send an e-mail message to the support site.

To do this, look at the address in the `To:' field of the send-pr
template. When you send unformatted e-mail to this address, GNATS
processes the message as a new problem report, filling in as many fields from
defaults as it can:

Synopsis

The `>Synopsis' field is filled in by the `Subject:' header.

Submitter ID

GNATS will try to derive the `>Submitter' field from the address
in the `From:' header.

Description

All of the text in the body of the e-mail message is put into the
`>Description' field. Each line of the text is indented by one space,
indicating that it is "quoted text" from the sender.

Other fields, such as category, version, severity, etc. are set to default
values (if the GNATS administrator has set them).

2.2.5 Helpful hints

There is no orthodox standard for submitting effective bug reports,
though you might do well to consult the section on submitting bugs for
GNU gcc in section `Reporting Bugs' in Using and Porting GNU CC, by Richard Stallman. This section contains
instructions on what kinds of information to include and what kinds of
mistakes to avoid.

In general, common sense (assuming such an animal exists) dictates the
kind of information that would be most helpful in tracking down and
resolving problems in software.

Include anything you would want to know if you were looking at
the report from the other end. There's no need to include every minute
detail about your environment, although anything that might be different
from someone else's environment should be included (your path, for
instance).

Narratives are often useful, given a certain degree of restraint. If a
person responsible for a bug can see that A was executed, and then B and
then C, knowing that sequence of events might trigger the realization of
an intermediate step that was missing, or an extra step that might have
changed the environment enough to cause a visible problem. Again,
restraint is always in order ("I set the build running, went to get a
cup of coffee (Columbian, cream but no sugar), talked to Sheila on the
phone, and then THIS happened...") but be sure to include anything
relevant.

Richard Stallman writes, "The fundamental principle of reporting bugs
usefully is this: report all the facts. If you are not sure
whether to state a fact or leave it out, state it!" This holds true
across all problem reporting systems, for computer software or social
injustice or motorcycle maintenance. It is especially important in the
software field due to the major differences seemingly insignificant
changes can make (a changed variable, a missing semicolon, etc.).

Submit only one problem with each Problem Report. If you have
multiple problems, use multiple PRs. This aids in tracking each problem
and also in analyzing the problems associated with a given program.

It never hurts to do a little research to find out if the bug you've
found has already been reported. Most software releases contain lists
of known bugs in the Release Notes which come with the software; see
your system administrator if you don't have a copy of these.

The more closely a PR adheres to the standard format, the less
interaction is required by a database administrator to route the
information to the proper place. Keep in mind that anything that
requires human interaction also requires time that might be better spent
in actually fixing the problem. It is therefore in everyone's best
interest that the information contained in a PR be as correct as
possible (in both format and content) at the time of submission.

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.

After the PR has been edited, the PR 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:' section
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.

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.4 Querying the database

Obtain information from the database by using the program
query-pr. query-pr uses search parameters you provide
to find matching Problem Reports in the database. You can invoke
query-pr from the shell or from within Emacs. query-pr
uses the same arguments whether it is invoked from the shell or from
Emacs.

PRs may be selected via the use of the --expr option, directly by
number, or by the use of the (now deprecated) field-specific query
operators.

By default, query options are connected with a logical AND. For
example,

query-pr --category=foo --responsible=bar

only prints PRs which have a Category field of `foo' and a Responsible
field of `bar'.

The --or option may be used to connect query options with a logical
OR. For example,

query-pr --category=baz --or --responsible=blee

prints PRs which have either a Category field of `baz' or a Responsible
field of `blee'.

It should be emphasized, however, that the use of these field-specific
options is strongly discouraged, since they exist only for compatibility
with older versions of GNATS and are likely to be deleted in the next
release. The expressions specified by the --expr option are much more
flexible (see below).

2.4.1 Invoking query-pr

From the shell, simply type query-pr, followed by any search
parameters you wish to exercise. From Emacs, type M-x
query-pr. query-pr prompts you for search parameters in the
minibuffer.

query-pr can also be accessed by electronic mail, if your version
of GNATS is configured for this. To use this feature, simply send
mail to the address `query-pr@your-site' with command
line arguments or options in the `Subject:' line of the mail
header. GNATS replies to your mail with the results of your query.
The default settings for the query-pr mail server are

--restricted --state="open|analyzed|feedback|suspended"

To override the `--state' parameter, specify
`--state=state' in the Subject: line of the mail
header. You can not query on confidential Problem Reports by mail.

Specifies the database to be used for the query. If no database is
specified, the database named default is assumed. (This option
overrides the database specified in the GNATSDB environment
variable; see 2.1 Environment variables and GNATS tools for more
information.)

--list-categories, -j

Lists the available PR categories for the selected database.

--list-states, -T

Lists the valid PR states for PRs in this database.

--list-responsible, -k

Lists the users that appear in the database's responsible list.

--list-submitters, -l

Lists the valid submitters for this database.

The previous --list-* options are deprecated and may be removed in
future releases of GNATS; their functionality can be replaced with

query-pr --valid-values field

where field is one of `Category', `Class',
`Responsible', `Submitter-Id', or `State'.

--list-databases

Lists the known databases.

--list-fields

Lists the entire set of field names for PRs in the selected database.

--list-input-fields

Lists the fields that should be provided when creating a new PR for the
currently-specified database. The fields are listed in an order that
would make sense when used in a template or form.

--field-type field

Returns the data type contained in PR field field. The current set of
data types includes `text', `multitext', `enum',
`multienum', `integer', `date', and
`text-with-regex-qualifier'.

--field-description field

Returns a human-readable description of the intended purpose of field.

--valid-values field

For fields of type `enum', a list of valid values (one per line) is
returned. Otherwise, a regular expression is returned that describes
the legal values in field.

--responsible-address name

The mail address of name is returned; name is assumed to be
a name either appearing in the database's responsible list, or is
otherwise a user on the system.

--print-sh-vars

A set of `/bin/sh' variables is returned that describe the selected
database. They include:

2.4.2 Formatting query-pr output

Printing formats for PRs are in one of three forms:

formatname

This is a named format which is described by the database (specifically,
these formats are described in the `dbconfig' file associated with the
database). The default configuration contains five such formats:
`standard', `full', `summary', `sql', and
`sql2'.

The first three are the ones most commonly used when performing queries.
standard is the format used by default if no other format is specified.

Use of the latter two are discouraged; they are merely kept for
historical purposes. Other named formats may have been added by the
database administrator.

fieldname

A single field name may appear here. Only the contents of this field
will be displayed.

"printf string" fieldname fieldname ...

This provides a very flexible mechanism for formatting PR output. (The
formatting is identical to that provided by the named formats described
by the database configuration, See section 4.3.5 Named query definitions. The
printf string can contain the following % sequences:

%[positionalspecifiers]s: Prints the field as a string. The
positional specifiers are similar to those of printf, as +, - and digit
qualifiers can be used to force a particular alignment of the field
contents.

%[positionalspecifiers]S: Similar to %s, except that the
field contents are terminated at the first space character.

%[positionalspecifiers]d: Similar to %s, except that the
field contents are written as a numeric value. For integer fields, the
value is written as a number. For enumerated fields, the field is
converted into a numeric equivalent (i.e. if the field can have two
possible values, the result will be either 1 or 2). For date fields,
the value is written as seconds since Jan 1, 1970.

%F: The field is written as it would appear within a PR, complete
with field header.

%D: For date fields, the date is written in a standard GNATS
format.

%Q: For date fields, the date is written in an arbitrary "SQL"
format.

2.4.3 Query expressions

Query expressions are used to select specific PRs based on their field
contents. The general form is

fieldname|"value" operator fieldname|"value" [booleanop ...]

value is a literal string or regular expression; it must be
surrounded by double quotes, otherwise it is interpreted as a fieldname.

fieldname is the name of a field in the PR.

operator is one of:

=

The value of the left-hand side of the expression must exactly match the
regular expression on the right-hand side of the expression.
See section Querying using regular expressions.

~

Some portion of the left-hand side of the expression must match the
regular expression on the right-hand side.

==

The value of the left-hand side must be equal to the value on the
right-hand side of the expression.

The equality of two values depends on what type of data is stored in the
field(s) being queried. For example, when querying a field containing
integer values, literal strings are interpreted as integers. The query
expression

Number == "0123"

is identical to

Number == "123"

as the leading zero is ignored. If the values were treated as strings
instead of integers, then the two comparisons would return different
results.

!=

The not-equal operator. Produces the opposite result of the == operator.

<,>

The left-hand side must have a value less than or greater than the
right-hand side. Comparisons are done depending on the type of data
being queried; in particular, integer fields and dates use a numeric
comparison, and enumerated fields are ordered depending on the numeric
equivalent of their enumerated values.

booleanop is either `|' (logical or), or `&' (logical
and). The query expression

Category="baz" | Responsible="blee"

selects all PRs with a Category field of `baz' or a Responsible
field of `blee'.

The not operator `!' may be used to negate a test:

! Category="foo"

searches for PRs where the category is not equal to the regular
expression foo.

Parentheses may be used to force a particular interpretation of the
expression:

!(Category="foo" & Submitter-Id="blaz")

skips PRs where the Category field is equal to `foo' and the
Submitter-Id field is equal to `blaz'. Parentheses may be nested
to any arbitrary depth.

Fieldnames can be specified in several ways. The simplest and most
obvious is just a name:

Category="foo"

which checks the value of the category field for the value foo.

A fieldname qualifier may be prepended to the name of the field; a colon
is used to separate the qualifier from the name. To refer directly to a
builtin field name:

builtin:Number="123"

In this case, `Number' is interpreted as the builtin name of the
field to
check. (This is useful if the fields have been renamed. For further
discussion of builtin field names, see The dbconfig file.

To scan all fields of a particular type, the fieldtype qualifier
may be
used:

fieldtype:Text="bar"

This searches all text fields for the regular expression `bar'.

Note that it is not required that the right-hand side of the expression
be a literal string. To query all PRs where the PR has been modified
since it was closed, the expression

Last-Modified != Closed-Date

will work; for each PR, it compares the value of its Last-Modified field
against its Closed-Date field, and returns those PRs where the values
differ. However, this query will also return all PRs with empty
Last-Modified or Closed-Date fields. To further narrow the search:

yields all PRs in the database whose `>State:' values match either
`open' or `analyzed' (see section Querying using regular expressions. This search is useful as a daily report that lists all
Problem Reports which require attention.

The following query:

query-pr --expr 'fieldtype:Text="The quick.*brown fox"'

yields all PRs whose TEXT fields contain the text `The quick'
followed by `brown fox' within the same field.
See section Querying using regular expressions, which also contains
further useful examples of query expressions.

2.5 The Emacs interface to GNATS

This section provides an overview of using GNATS with Emacs. It
does not describe the use of Emacs itself, for detailed instructions
on using Emacs, see section `Top' in GNU Emacs. For
installation instructions of the GNATS Emacs mode, see
3.2 Installing the utilities.

Please note the Emacs interface was completely rewritten between
GNATS 3 and GNATS 4. It now uses gnatsd,
B. The GNATS network server -- gnatsd, exclusively for its operations and uses modern Emacs
features like faces. Its features are not complete though, you can
send your suggestions and patches to the appropriate GNATS
mailing list, E. GNATS support.

2.5.2 Querying Problem Reports

Querying the database is performed by the M-x query-pr command.
The command prompts for the query expression, 2.4.3 Query expressions,
and displays a buffer with the list of the matching Problem Reports.

The list of the Problem Reports is displayed in the `summary'
query format, 2.4.2 Formatting query-pr output. Currently, the
display format cannot be changed and it must output each Problem
Report's number in the first column.

The Problem Report list buffer is put in the view mode, section `Misc File Ops' in GNU Emacs. You can use most of the standard view mode
commands in it. Additionally, the following special commands are
available:

2.5.3 Submitting new Problem Reports

You can submit new Problem Reports with the command M-x send-pr.
The command puts you to the problem editing buffer, 2.5.4 Editing Problem Reports. The buffer is prefilled with the initial report fields and
their default values, if defined. You can use the usual Problem
Report editing commands, 2.5.4 Editing Problem Reports. When you have filled in
all the fields, you can send the Problem Report by presing C-c
C-c.

If you run M-x send-pr with a prefix argument, it runs the
gnats-change-database command before putting you to the editing
buffer, 2.5.6 Changing the database.

You can set the following variables to get some fields pre-filled:

gnats-default-organization

Default value of the `Organization' field used in new Problem Reports.

gnats-default-submitter

Default value of the `Submitter-Id' field used in new Problem Reports.

2.5.4 Editing Problem Reports

To edit a particular Problem Report, use the command M-x
edit-pr. It asks for a Problem Report number and puts the given
Problem Report in the editing buffer. See section 2.5.5 The Problem Report editing buffer,
for information how to edit the Problem Report in the buffer and how
to submit your changes.

2.5.5 The Problem Report editing buffer

When you invoke a Problem Report editing command, the Problem Report
is put into a special editing buffer. The Problem Report is formatted
similarly to the query-pr -F output, 2.4.2 Formatting query-pr output. Field identifiers are formatted as

>Field:

with the text of the field following the identifier on the same line
for single-line fields or starting on the next line for multi-line
fields.

The Problem Report editing mode tries to prevent you from violating
the Problem Report format and the constraints put on the possible
field values. Generally, you can use usual editing commands, some of
them have a slightly modified behavior though. (If you encounter a
very strange behavior somewhere, please report it as a bug,
E. GNATS support.)

You can move between fields easily by pressing the TAB
(gnats-next-field) or M-TAB
(gnats-previous-field) keys.

The field tags are read-only and you cannot edit them nor delete them.
If you want to "remove" a field, just make its value empty.

Editing a field value depends on the type of the edited field,
4.3.3 Field datatypes. For text fields, you can edit the value
directly, assuming you preserve the rule about single-line and
multi-line values mentioned above.

For enumerated fields, you cannot edit the value directly. You can
choose it from the list of the allowed values, either from the menu
popped up by pressing the middle mouse button or from within
minibuffer by pressing any key on the field's value. If the pressed
key matches any of the allowed field values, that value is put as the
default value after the minibuffer prompt. You can also cycle through
the allowed field values directly in the editing buffer using the
SPACE key. Enumerated field values are marked by a special
face to not confuse you; you must have enabled font lock mode to
benefit from this feature, section `Font Lock' in GNU Emacs.

Some field values can be read-only, you cannot edit them at all.

Once you have edited the Problem Report as needed, you can send it to
the server with the C-c C-c command
(gnats-apply-or-submit). Successful submission is reported by
a message and the buffer modification flag in mode line is cleared.
Then you can either kill the buffer or continue with further
modifications.

2.5.6 Changing the database

By default, the Emacs interface connects to the default database,
4.2 The databases file. If you want to connect to another database, use
the command M-x gnats-change-database. It will ask you for the
database name to use, server and port it can be accessed on, and your
login name.

If you want to use the gnatsd command, B. The GNATS network server -- gnatsd,
directly, without connecting to a remote server or the localhost
connection port, provide your local file system full path to
gnatsd as the server name. Port number does not matter in
this case.

If the database requires a password to allow you the access to it, you
are prompted for the password the first time you connect to the
database. If you provide an invalid password, you cannot connect to
the database anymore and you have to run the M-x
gnats-change-database command again.

2.5.7 dbconfig mode

The Emacs interface defines a simple major mode
gnats-dbconfig-mode for editing `dbconfig' files,
4.3 The dbconfig file. It defines basic mode attributes like character
syntax and font lock keywords, it does not define any special commands
now.

2.5.8 Other commands

M-x unlock-pr

Ask for a Problem Report number and unlock that Problem Report. This
function is useful if connection to a GNATS server was
interrupted during an editing operation and further modifications of
the Problem Report are blocked by a stealth lock.