This is gnats.info, produced by makeinfo version 4.2 from gnats.texi.

START-INFO-DIR-ENTRY
* Keeping Track: (gnats).	GNU Problem Report Management System
END-INFO-DIR-ENTRY

   Copyright (C) 2002 Milan Zamazal Copyright (C) 1993, 1995, 2001 Free
Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.


File: gnats.info,  Node: Top,  Next: Introduction,  Up: (dir)

Overview
********

   This manual documents GNATS, the GNU Problem Report Management
System, version 4.0-beta2.  GNATS is a bug-tracking tool designed for
use at a central "Support Site".  Users who experience problems use
electronic mail, web-based or other clients communicating with the
GNATS network daemon running at the support site or direct database
submissions to communicate these problems to "maintainers" at that
Support Site.  GNATS partially automates the tracking of these "Problem
Reports" ("PR"s) by:

   * organizing problem reports into a database and notifying
     responsible parties of suspected bugs;

   * allowing support personnel and their managers to edit and query
     accumulated bugs; and

   * providing a reliable archive of problems (and their subsequent
     solutions) with a given program.

   GNATS offers many of the same features offered by more generalized
databases, including editing, querying, and basic reporting.  The GNATS
database itself is an ordered repository for problem reports; each PR
receives a unique, incremental "PR number" which identifies it
throughout its lifetime.  For a discussion on the working system
adopted by GNATS, see *Note The database paradigm: Paradigm.

   You can access the submitting, editing, and querying functions of
GNATS from within GNU Emacs.  *Note The GNATS user tools: GNATS user
tools.

Note on this version of the manual
==================================

   This manual is in the process of being revised for version 4 of
GNATS.  The status of the different sections is as follows:

   * Chapter 1 _Introducing GNATS_
     Version 4 complete.

   * Chapter 2 _The GNATS User Tools_
     Version 4 complete.

   * Chapter 3 _Installing GNATS_
     Version 4 complete.

   * Chapter 4 _GNATS Administration_
     Version 4 complete.

   * Appendix A _Where GNATS lives_
     Version 4 complete.

   * Appendix B _The GNATS network server - `gnatsd'_
     Version 4 complete.

   * Appendix C _Controlling access to databases_
     Version 4 complete.

   * Appendix D _Querying using regular expressions_
     Version 4 complete.

   * Appendixes E and F were written specifically for GNATS 4.

* Menu:

* Introduction::          Introducing GNATS.
* GNATS user tools::      The GNATS user tools.
* Installation::          Installing GNATS.
* Management::            GNATS Administration.
* Locations::             Where GNATS lives.
* gnatsd::                The GNATS network server.
* Access Control::        Controlling access to GNATS databases.
* Regexps::               Querying using regular expressions.
* dbconfig recipes::      Useful dbconfig tricks.
* Support::               GNATS related sites and mailing lists.
* Index::


File: gnats.info,  Node: Introduction,  Next: GNATS user tools,  Prev: Top,  Up: Top

Introducing GNATS
*****************

   Any support organization realizes that a large amount of data flows
back and forth between the maintainers and the users of their products.
This data often takes the form of problem reports and communication via
electronic mail.  GNATS addresses the problem of organizing this
communication by defining a database made up of archived and indexed
problem reports.

   GNATS was designed as a tool for software maintainers.  It consists
of several utilities which, when used in concert, formulate and
administer a database of Problem Reports grouped by site-defined
"problem categories".  It allows a support organization to keep track
of problems (hence the term "Problem Report") in an organized fashion.
Essentially, GNATS acts as an active archive for field-separated
textual data.

* Menu:

* Paradigm::       The database paradigm
* Flowchart::      Flowchart of GNATS activities
* States::         States of Problem Reports
* Fields::         Problem Report format


File: gnats.info,  Node: Paradigm,  Next: Flowchart,  Up: Introduction

The database paradigm
=====================

   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" (*note GNATS data fields:
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".  *Note GNATS administration: Management.

   Each PR is a separate file within a main repository (*note Where
GNATS lives: Locations.).  Editing access to the database is regulated
to maintain consistency.  To make queries on the database faster, an
index is kept automatically (*note The `index' file: 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.

   * Maintainers, managers and administrators can use `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
*Note GNATS Administration: Management, 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.  *Note Overview of GNATS configuration: 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 (*note GNATS
Administration: Management.).

   Once a problem is recorded in the database, work can begin toward a
solution.  A problem's initial "state" type is "open" (*note States of
Problem Reports: States.).  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.  (*Note Editing existing Problem Reports:
edit-pr.  For information on the `Audit-Trail' field, see *Note Problem
Report format: Fields.)

   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 *Note States of Problem Reports: States.)

   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 *Note The `dbconfig' file: dbconfig file and *Note States of
Problem Reports: States.)


File: gnats.info,  Node: Flowchart,  Next: States,  Prev: Paradigm,  Up: Introduction

Flowchart of GNATS activities
=============================

   This informal flowchart shows the relationships of the GNATS tools
to each other and to the files with which they interoperate.



     +===========+       +===========+        +============+
     # USER SITE #       # USER SITE #        # USER SITE  #
     #           #       #           #        #            #
     # *send-pr* #       # *send-pr* #        # Web client #
     +=====|=====+       +=====|=====+        +=====|======+
           |                   V                    |
           `--------->    Email/gnatsd...   <-------'
                     ,--->     |
     +===============|=========|===================+
     # SUPPORT SITE  |         `---> /etc/aliases  #
     #          *send-pr*                |         #
     #     +-----------------------------V--------+#
     #     | GNATS        DATABASEDIR/gnats-queue/|#
     #     |                             |        |#
     #     |        _________            V        |#
     #     |       |*file-pr*|<--- *queue-pr -r*  |#
     #     |       |         |                    |#
     #  _  |       |  valid  |                    |#
     # |M| |       |Category?|N--.                |#
     # |A| |       |_________|   |      GNATS     |#
     # |I| |              Y|     |  ADMINISTRATOR |#
     # |N| |               |     |                |#
     # |T|<----------------|     |                |#
     # |A| |               |     |  .-> *edit-pr* |#
     # |I|--->*edit-pr*-.  |     V  |           | |#
     # |N| |            |  |DATABASEDIR/pending | |#
     # |E|<--*query-pr* |  |                    | |#
     # |R| |       |    |  |                    | |#
     # |S| |       |    V  V                    V |#
     # |_| |+------------------------------------+|#
     #     ||         GNATS Database             ||#
     #     ||  DATABASEDIR/CATEGORY/GNATS-ID     ||#
     #     |+------------------------------------+|#
     #     +--------------------------------------+#
     +=============================================+




File: gnats.info,  Node: States,  Next: Fields,  Prev: Flowchart,  Up: Introduction

States of Problem Reports
=========================

   Each PR goes through a defined series of states between origination
and closure.  By default, the originator of a PR receives notification
automatically of any state changes.

   Unless your site has customized states (*note states file:
(gnats)states file.), GNATS uses these states:

"open"
     The initial state of a Problem Report.  This means the PR has been
     filed and the responsible person(s) notified.

"analyzed"
     The responsible person has analyzed the problem.  The analysis
     should contain a preliminary evaluation of the problem and an
     estimate of the amount of time and resources necessary to solve
     the problem.  It should also suggest possible workarounds.

"feedback"
     The problem has been solved, and the originator has been given a
     patch or other fix.  The PR remains in this state until the
     originator acknowledges that the solution works.

"closed"
     A Problem Report is closed ("the bug stops here") only when any
     changes have been integrated, documented, and tested, and the
     submitter has confirmed the solution.

"suspended"
     Work on the problem has been postponed.  This happens if a timely
     solution is not possible or is not cost-effective at the present
     time.  The PR continues to exist, though a solution is not being
     actively sought.  If the problem cannot be solved at all, it
     should be closed rather than suspended.


File: gnats.info,  Node: Fields,  Prev: States,  Up: Introduction

Problem Report format
=====================

   The format of a PR is designed to reflect the nature of GNATS as a
database.  Information is arranged into "fields", and kept in
individual records (Problem Reports).

   A Problem Report contains two different types of fields: "Mail
Header" fields, which are used by the mail handler for delivery, and
"Problem Report" fields, which contain information relevant to the
Problem Report and its submitter.  A Problem Report is essentially a
specially formatted electronic mail message.

   Problem Report fields are denoted by a keyword which begins with `>'
and ends with `:', as in `>Confidential:'.  Fields belong to one of
eight data types as listed in *Note Field datatypes reference::.  As of
version 4 of GNATS all characteristics of fields, such as field name,
data type, allowed values, permitted operations, on-change actions etc.
are configurable.

   For details, see *note The `dbconfig' file: dbconfig file..

Example Problem Report
----------------------

   The following is an example Problem Report with the fields that
would be present in a standard GNATS configuration.  Mail headers are
at the top, followed by GNATS fields, which begin with `>' and end with
`:'.  The `Subject:' line in the mail header and the `Synopsis' field
are usually duplicates of each other.

     Message-Id:  MESSAGE-ID
     Date:        DATE
     From:        ADDRESS
     Reply-To:    ADDRESS
     To:          BUG-ADDRESS
     Subject:     SUBJECT
     
     >Number:       GNATS-ID
     >Category:     CATEGORY
     >Synopsis:     SYNOPSIS
     >Confidential: yes _or_ no
     >Severity:     critical, serious, _or_ non-critical
     >Priority:     high, medium _or_ low
     >Responsible:  RESPONSIBLE
     >State:        open, analyzed, suspended, feedback, _or_ closed
     >Class:        sw-bug, doc-bug, change-request, support,
     duplicate, _or_ mistaken
     >Submitter-Id: SUBMITTER-ID
     >Arrival-Date: DATE
     >Originator:   NAME
     >Organization: ORGANIZATION
     >Release:      RELEASE
     >Environment:
        ENVIRONMENT
     >Description:
        DESCRIPTION
     >How-To-Repeat:
        HOW-TO-REPEAT
     >Fix:
        FIX
     >Audit-Trail:
     APPENDED-MESSAGES...
     State-Changed-From-To: FROM-TO
     State-Changed-When: DATE
     State-Changed-Why:
        REASON
     Responsible-Changed-From-To: FROM-TO
     Responsible-Changed-When: DATE
     Responsible-Changed-Why:
        REASON
     >Unformatted:
        MISCELLANEOUS

* Menu:

* Field datatypes reference::
* Mail header fields::
* Problem Report fields::


File: gnats.info,  Node: Field datatypes reference,  Next: Mail header fields,  Up: Fields

Field datatypes reference
-------------------------

   The following is a short reference to the characteristics of the
different field types.

   For details, see *Note Field datatypes::.

`text'
     A one-line text string.

`multitext'
     Multiple lines of text.

`enum'
     The value in this field is required to be from a list of specified
     values, defined at the Support Site.

     (*Note The `dbconfig' file: dbconfig file, for details.

`multienum'
     Similar to the `enum' datatype, except that the field can contain
     multiple values.

`enumerated-in-file'
     Similar to `enum', but the allowed field values are listed in a
     separate file on the GNATS server.

`multi-enumerated-in-file'
     Similar to `enumerated-in-file', except that the field can contain
     multiple values.

`date'
     Used to hold dates.

`integer'
     Used to hold integer numbers.


File: gnats.info,  Node: Mail header fields,  Next: Problem Report fields,  Prev: Field datatypes reference,  Up: Fields

Mail header fields
------------------

   A Problem Report may contain any mail header field described in the
Internet standard RFC-822.  The `send-pr' tool can be configured either
to submit PRs to the support site by e-mail or by talking directly to
the `gnatsd' network daemon on the GNATS server.  This is also true for
other client tools such as Gnatsweb.  Even when these tools are set up
submit PRs directly to `gnatsd', they will still include mail header
fields that identify the sender and the subject in the submitted PR:

`To:'
     The mail address for the Support Site, automatically supplied by
     the tool used to submit the PR or by the originator if plain
     e-mail was used.

`Subject:'
     A terse description of the problem.  This field normally contains
     the same information as the `Synopsis' field.

`From:'
     Supplied automatically when PRs are submitted by plain e-mail and
     when well-behaved tools such as `send-pr' are used; should always
     contain the originator's e-mail address.

`Reply-To:'
     A return address to which electronic replies can be sent; in most
     cases, the same address as the `From:' field.

   One of the configurable options for GNATS is whether or not to
retain `Received-By' headers, which often consume a lot of space and
are not often used.  *Note The dbconfig file: dbconfig file.


File: gnats.info,  Node: Problem Report fields,  Prev: Mail header fields,  Up: Fields

Problem Report fields
---------------------

Field descriptions
------------------

   In a standard GNATS installation, certain fields will always be
present in a Problem Report.  If a PR arrives without one or more of
these fields, GNATS will add them, and if they have default values set
by the configuration at the Support Site, they will be filled in with
these values.  Certain tools such as `send-pr' are set up to provide
sensible defaults for most fields (*note The send-pr.conf configuration
file: send-pr.conf file..)

   In the list below, the field type (`text', `multitext',
`enumerated', etc.) is supplied in parantheses.  The different field
types are explained briefly in *Note Field datatypes reference::.

`Submitter-Id'
     (`enumerated-in-file') A unique identification code assigned by the
     Support Site.  It is used to identify all Problem Reports coming
     from a particular site.  Submitters without a value for this field
     can invoke `send-pr' with the `--request-id' option to apply for
     one from the support organization.  Problem Reports from those not
     affiliated with the support organization should use the default
     value of `net' for this field.

     *Note The `submitters' file: submitters file, for details.

`Notify-List'
     (`text') Comma-separated list of e-mail-addresses of people to
     notify when the PR changes significantly, i.e. when the Audit-Trail
     changes.  This list is independent from the Notify subfield of
     entries in the `categories' file of the GNATS database.

`Originator'
     (`text') Originator's real name.  Note that the Submitter and
     Originator might not be the same person/entity in all cases.

`Organization'
     (`multitext') The originator's organization.

`Confidential'
     (`enum') Use of this field depends on the originator's relationship
     with the support organization; contractual agreements often have
     provisions for preserving confidentiality.  Conversely, a lack of a
     contract often means that any data provided will not be considered
     confidential.  Submitters should be advised to contact the support
     organization directly if this is an issue.

     If the originator's relationship to the support organization
     provides for confidentiality, then if the value of this field is
     `yes' the support organization treats the PR as confidential; any
     code samples provided are not made publicly available.

`Synopsis'
     (`text') One-line summary of the problem.  `send-pr' copies this
     information to the `Subject' line when you submit a Problem Report.

`Severity'
     (`enum') The severity of the problem.  By default, accepted values
     include:

    `critical'
          The product, component or concept is completely
          non-operational or some essential functionality is missing.
          No workaround is known.

    `serious'
          The product, component or concept is not working properly or
          significant functionality is missing.  Problems that would
          otherwise be considered `critical' are usually rated
          `serious' when a workaround is known.

    `non-critical'
          The product, component or concept is working in general, but
          lacks features, has irritating behavior, does something
          wrong, or doesn't match its documentation.

`Priority'
     (`enumerated') How soon the originator requires a solution.
     Accepted values include:

    `high'
          A solution is needed as soon as possible.

    `medium'
          The problem should be solved in the next release.

    `low'
          The problem should be solved in a future release.

`Category'
     (`enumerated-in-file') The name of the product, component or
     concept where the problem lies.  The values for this field are
     defined by the Support Site.  *Note The `categories' file:
     categories file, for details.

`Class'
     (`enumerated-in-file') The class of a problem in a default GNATS
     installation can be one of the following:

    `sw-bug'
          A general product problem.  (`sw' stands for "software".)

    `doc-bug'
          A problem with the documentation.

    `change-request'
          A request for a change in behavior, etc.

    `support'
          A support problem or question.

    `duplicate (PR-NUMBER)'
          Duplicate PR.  PR-NUMBER should be the number of the original
          PR.

    `mistaken'
          No problem, user error or misunderstanding.  This value can
          only be set by tools at the Support Site, since it has no
          meaning for ordinary submitters.

     *Note The `classes' file: classes file, for details.

`Release'
     (`text') Release or version number of the product, component or
     concept.

`Environment'
     (`multitext') Description of the environment where the problem
     occurred: machine architecture, operating system, host and target
     types, libraries, pathnames, etc.

`Description'
     (`multitext') Precise description of the problem.

`How-To-Repeat'
     (`multitext') Example code, input, or activities to reproduce the
     problem.  The support organization uses example code both to
     reproduce the problem and to test whether the problem is fixed.
     Include all preconditions, inputs, outputs, conditions after the
     problem, and symptoms.  Any additional important information
     should be included.  Include all the details that would be
     necessary for someone else to recreate the problem reported,
     however obvious.  Sometimes seemingly arbitrary or obvious
     information can point the way toward a solution.  See also *Note
     Helpful hints: Helpful hints.

`Fix'
     (`multitext') A description of a solution to the problem, or a
     patch which solves the problem.  (This field is most often filled
     in at the Support Site; we provide it to the submitter in case he
     or she has solved the problem.)

GNATS adds the following fields when the PR arrives at the Support Site:

`Number'
     (`enumerated') The incremental identification number for this PR.
     This is included in the automated reply to the submitter (if that
     feature of GNATS is activated; *note The `dbconfig' file: dbconfig
     file.).  It is also included in the copy of the PR that is sent to
     the maintainer.

     The `Number' field is often paired with the `Category' field as

          CATEGORY/NUMBER

     in subsequent email messages.  This is GNATS' way of tracking
     followup messages that arrive by mail so that they are filed as
     part of the original PR.

`State'
     (`enumerated') The current state of the PR.  In default GNATS
     installations, accepted values are:

    `open'
          The PR has been filed and the responsible person notified.

    `analyzed'
          The responsible person has analyzed the problem.

    `feedback'
          The problem has been solved, and the originator has been
          given a patch or other fix.  Support organizations may also
          choose to temporarily "park" PRs that are awaiting further
          input from the submitter under this state.

    `closed'
          The changes have been integrated, documented, and tested, and
          the originator has confirmed that the solution works.

    `suspended'
          Work on the problem has been postponed.

     The initial state of a PR is `open'.  *Note States of Problem
     Reports: States.

`Responsible'
     (`text') The person at the Support Site who is responsible for this
     PR.  GNATS retrieves this information from the `categories' file
     (*note The `categories' file: categories file.).

`Arrival-Date'
     (`date') The time that this PR was received by GNATS.  The date is
     provided automatically by GNATS.

`Date-Required'
     (`date') The date by which a fix is required.  This is up to the
     maintainers at the Support Site to determine, so this field is not
     available until after the PR has been submitted.

`Audit-Trail'
     (`multitext') Tracks related electronic mail as well as changes in
     the `State' and `Responsible' fields with the sub-fields:

    `State-Changed-<From>-<To>: OLDSTATE>-<NEWSTATE'
          The old and new `State' field values.

    `Responsible-Changed-<From>-<To>: OLDRESP>-<NEWRESP'
          The old and new `Responsible' field values.

    `State-Changed-By: NAME'
    `Responsible-Changed-By: NAME'
          The name of the maintainer who effected the change.

    `State-Changed-When: TIMESTAMP'
    `Responsible-Changed-When: TIMESTAMP'
          The time the change was made.

    `State-Changed-Why: REASON...'
    `Responsible-Changed-Why: REASON...'
          The reason for the change.

     The `Audit-Trail' field also contains any mail messages received by
     GNATS related to this PR, in the order received.  GNATS needs to
     find a CATEGORY/NUMBER at the beginning of the Subject field of
     received e-mail in order to be able to file it correctly.

`Unformatted'
     (`multitext') Any random text found outside the fields in the
     original Problem Report.

   During a Problem Report's journey from `open' to `closed', two more
fields, `Last-Modified' and `Closed Date' (both of type `date') will be
added.


File: gnats.info,  Node: GNATS user tools,  Next: Installation,  Prev: Introduction,  Up: Top

The GNATS User Tools
********************

   This chapter describes the user tools distributed with GNATS.  The
GNATS administrative and internal tools are described in *Note GNATS
Administration: Management. 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 (*note
     Submitting Problem Reports: send-pr.).

`query-pr'
     Used to query the GNATS database (*note Querying the database:
     query-pr.).

`edit-pr'
     Used to edit Problem Reports (to record new data, to change the
     responsible party, etc.) (*note Editing existing Problem Reports:
     edit-pr.).

* Menu:

* Environment::       Environment variables and GNATS tools
* send-pr::           Submitting Problem Reports
* edit-pr::           Editing existing Problem Reports
* query-pr::          Querying the database
* Emacs::             The Emacs interface


File: gnats.info,  Node: Environment,  Next: send-pr,  Up: GNATS user tools

Environment variables and GNATS tools
=====================================

   All the GNATS user tools honor the `GNATSDB' environment variable
which is used to determine which database to use.  For a local
database, it contains the name of the database to access.

   For network access via gnatsd, it contains a colon-separated list of
strings that describe the remote database in the form

     SERVER:PORT:DATABASENAME:USERNAME:PASSWORD

   Any of the fields may be omitted except for SERVER, but at least one
colon must appear; otherwise, the value is assumed to be the name of a
local database.

   If `GNATSDB' is not set and no command-line options are used to
specify the database, it is assumed that the database is local and that
its name is `default'.


File: gnats.info,  Node: send-pr,  Next: edit-pr,  Prev: Environment,  Up: GNATS user tools

Submitting Problem Reports
==========================

   Use `send-pr' to submit Problem Reports to the database.  `send-pr'
is a shell script which composes a template for submitters to complete.

   You can invoke `send-pr' from a shell prompt, or from within GNU
Emacs using `M-x send-pr' (*note Submitting Problem Reports from Emacs:
Emacs submitting..)

* Menu:

* using send-pr::             Creating new Problem Reports
* send-pr in Emacs::          Using send-pr from within Emacs
* send-pr from the shell::    Invoking send-pr from the shell
* Submitting via e-mail::     Submitting a Problem Report via direct e-mail
* Helpful hints::


File: gnats.info,  Node: send-pr from the shell,  Next: Submitting via e-mail,  Prev: send-pr in Emacs,  Up: send-pr

Invoking `send-pr' from the shell
---------------------------------

     send-pr [ -b | --batch ]
             [ -d DATABASE | --database DATABASE ]
             [ -f FILE | --file FILE ]
             [ -p | --print ] [ --request-id ]
             [ -s SEVERITY | --severity SEVERITY ]
             [ -V | --version ] [ -h | --help ]

   Invoking `send-pr' with no options assumes that you want to submit
to the local GNATS database named DEFAULT and calls the editor named in
your environment variable `EDITOR' on a PR template for this database.

`-b'
`--batch'
     Suppresses printing of most of the messages `send-pr' usually
     prints while running.

`-d DATABASE, --database DATABASE'
     Specifies the database to which the PR is to be submitted; if no
     database is specified, the local database named `default' is
     assumed.  This option overrides the database specified in the
     `GNATSDB' environment variable.  DATABASE can also be set to a
     remote database by using the format for `GNATSDB' described in
     *Note Environment variables and GNATS tools: Environment.

`-f PROBLEM-REPORT'
`--file PROBLEM-REPORT'
     Specifies a file, PROBLEM-REPORT, where a completed Problem Report
     or a PR template exists.  `send-pr' verifies that the contents of
     the file constitute a valid PR and asks you if you want to edit it
     or send it directly.  If the PR text is invalid you will be told
     what is wrong and be given the option to edit it. If
     PROBLEM-REPORT is `-', `send-pr' reads from standard input.

`-p'
`--print'
     Displays the PR template for the specified database, or if the
     `-d' or `--database' options aren't specified, print the template
     for the local DEFAULT database.  No PR is submitted.

`--request-id'
     Sends a request for a `Submitter-Id' to the Support Site.

`-s SEVERITY'
`--severity SEVERITY'
     Sets the initial value of the `Severity' field to SEVERITY.

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

`-h'
`--help'
     Displays a usage summary for `send-pr'.  No mail is sent.


File: gnats.info,  Node: send-pr in Emacs,  Next: send-pr from the shell,  Prev: using send-pr,  Up: send-pr

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 (*note Introduction:
(emacs)Introduction.).

   Call `send-pr' with `M-x send-pr'.(1)  `send-pr' responds with a
preconfigured Problem Report template.  The Emacs interface is
described in more detail in a separate section, *Note The Emacs
interface to GNATS: Emacs.

   ---------- Footnotes ----------

   (1) If typing `M-x send-pr' doesn't work, see your system
administrator for help loading `gnats.el' into Emacs.


File: gnats.info,  Node: using send-pr,  Next: send-pr in Emacs,  Up: send-pr

The Problem Report template
---------------------------

   Invoking `send-pr' presents a PR "template" with a number of fields
already filled in with default values for the database you are
submitting to.  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

   * Mail Header

   * GNATS fields

   The *Comments section* at the top of the template contains basic
instructions for completing the Problem Report, as well as a list of
valid entries for the `Category' field.  One (and only one) of these
values should be placed in the `Category' field further down in the
Problem Report.

     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:

   The comments lines 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.)

   The *Mail Header* section of the template contains a standard mail
header constructed by `send-pr'.  `send-pr' can be set up to submit PRs
by e-mail or by speaking directly to the GNATS server, but since this
header is part of the standard format of Problem Reports, `send-pr'
includes it even when it is set up to speak directly to the server.

     To: PR SUBMISSION ADDRESS
     Subject: _complete this field_
     From: YOUR-LOGIN@YOUR-SITE
     Reply-To: YOUR-LOGIN@YOUR-SITE
     X-send-pr-version: send-pr 4.0-beta2

`send-pr' automatically completes all the mail header fields except the
`Subject' line with default values.  (*Note Problem Report format:
Fields.)

   The *GNATS fields* below the mail header form the bulk of a GNATS
Problem Report.

   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.  *Note Helpful
hints: Helpful hints, for suggestions as to what kinds of information
to include.

   The mechanisms `send-pr' uses to fill in default values is as
follows: Your preconfigured `Submitter-Id' is taken from the local
`send-pr.conf' configuration file.  `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'.  If these variables aren't set in you environment,
`send-pr' uses the values set in the local `send-pr.conf' configuration
file, if that exists.  If not, these values are left blank in the
template.  `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.

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

     >Submitter-Id: _your submitter-id_
     >Originator:   _your name here_
     >Organization:
         _your organization_
     >Confidential:<[ yes | no ] (one line)>
     >Synopsis:    <synopsis of the problem (one line)>
     >Severity:    <[non-critical | serious | critical](one line)>
     >Priority:    <[ low | medium | high ] (one line)>
     >Category:    <name of the product (one line)>
     >Class:       <[sw-bug | doc-bug | change-request | support]>
     >Release:     <release number (one line)>
     >Environment:
              <machine, os, target, libraries (multiple lines)>
     
     >Description:
            <precise description of the problem (multiple lines)>
     >How-To-Repeat:
            <code/input/activities to reproduce (multiple lines)>
     >Fix:
            <how to correct or work around the problem, if known
             (multiple lines)>

   When you finish editing the Problem Report, `send-pr' validates the
contents and if it looks OK either submits it directly to the GNATS
server or submits it by mail to the address named in the `To' field in
the mail header.

   If your PR contains one or more invalid field values, `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 they are received.


File: gnats.info,  Node: Submitting via e-mail,  Next: Helpful hints,  Prev: send-pr from the shell,  Up: send-pr

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 PR
submission e-mail address of the support site (This address should be
published by the support site.)

   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 of the
     e-mail message.

`Submitter ID'
     GNATS will try to derive the `Submitter' field from the address in
     the `From' header of the e-mail.

`Description'
     All of the text in the body of the e-mail message is put into the
     `Description' field.

   Other fields, such as `Category', `Version', `Severity', etc. are
set to default values as defined by the GNATS administrator.


File: gnats.info,  Node: Helpful hints,  Prev: Submitting via e-mail,  Up: send-pr

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 *Note Reporting Bugs: (gcc)Bugs, 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.


File: gnats.info,  Node: edit-pr,  Next: query-pr,  Prev: send-pr,  Up: GNATS user tools

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' (*note Problem Report
format: Fields.).  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 (*note The `index' file: index file.).  For
information on `pr-edit', the main driver for `edit-pr', see *Note
Internal utilities: Internal utils.

   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.

* Menu:

* edit-pr from the shell::  Invoking `edit-pr' from the shell


File: gnats.info,  Node: edit-pr from the shell,  Up: edit-pr

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.


File: gnats.info,  Node: query-pr,  Next: Emacs,  Prev: edit-pr,  Up: GNATS user tools

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

* Menu:

* Invoking query-pr::
* Formatting query-pr output::
* Query expressions::
* Example queries::

