     [file version.texi not included]

     START-INFO-DIR-ENTRY
     * send-pr: (send-pr).           Reporting problems--using send-pr
     END-INFO-DIR-ENTRY

Copyright © 1993, 1994 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.

Overview
********

This manual documents send-pr, version VERSION, which uses electronic mail to submit support questions and problem reports to a central Support Site.  No body of work is perfect, and support organizations understand this; send-pr is designed to allow users who have problems to submit reports of these problems to sites responsible for supporting the products in question, in a defined form which can be read by an electronically managed database.

send-pr is part of a suite of programs known collectively as GNATS, the GNU Problem Report Management System.  GNATS consists of several programs which, used in concert, formulate and partially administer a database of Problem Reports, or PRs, at a central Support Site.  A PR goes through several states in its lifetime; GNATS tracks the PR and all information associated with it through each state and finally acts as an archive for PRs which have been closed.

Because send-pr exists as a shell (/bin/sh) script and as an Elisp file for use with GNU Emacs, it can be used from any machine on your network which can run a shell script and/or Emacs.

In general, you can use any editor and mailer to submit valid Problem Reports, as long as the format required by GNATS is preserved. send-pr automates the process, however, and ensures that certain fields necessary for automatic processing are present.  send-pr is strongly recommended for all initial problem-oriented correspondence with your Support Site.  The organization you submit Problem Reports to supplies an address to which further information can be sent; the person responsible for the category of the problem you report contacts you directly.

Details about send-pr and GNATS
*******************************

A Problem Report is a message that describes a problem you are having with a body of work.  send-pr organizes this message into a form which can be understood and automatically processed by GNATS, the GNU Problem Report Management System.  A Problem Report is organized into fields which contain data describing you, your organization, and the problem you are announcing (see Problem Report format).  Problem Reports go through several defined states in their lifetimes, from open to closed (see States of Problem Reports).

     [file states.texi not included]

     [file fields.texi not included]

Editing and sending PRs
***********************

     [file s-usage.texi not included]

An Example
**********

Cygnus Support in Mountain View, CA, uses GNATS and send-pr extensively for their support activities.  As a support company, Cygnus finds problem tracking to be a crucial part of everyday business. Cygnus supports the GNU compiling tools (including GNATS and send-pr) over several many platforms

With each shipment of the Cygnus Support Developer's Kit, customers receive the latest version of send-pr, which contains an up-to-date listing of valid categories (values for the >Category: field).  Using these tools, Cygnus' customers can communicate their problems to Cygnus effectively and receive automatic confirmation of receipt as well as notification of changes in the status of their reported problems.  Much of Cygnus' support mechanism relies on electronic mail.

As an example, let's pretend we're a customer of Cygnus Support, and that we're having a problem compiling some of our software using the GNU C compiler, which Cygnus supports.

Assume that we're getting an error in our bifrabulator program wherein the prestidigitation routines don't match with the whatsitsname.  We've made sure we're following the rules of the program and checked the Release Notes from Cygnus and found that the bug isn't already known.  In other words, we're pretty sure we've found a bug.

Our first step is to call send-pr.  It really doesn't matter whether we use send-pr from the shell or from within Emacs. Indeed, if we use Emacs as a primary editor, calling send-pr from the shell is likely to start send-pr in an Emacs buffer anyway. So, since our company, Imaginary Software, Ltd., uses GNU software extensively, we're pretty familiar with Emacs, so from within Emacs we type

     M-x send-pr

and we're greeted with the following screen:

     SEND-PR: -*- text  -*-
     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: Please consult the manual if you are not sure
     SEND-PR: how to fill out a problem report.
     SEND-PR:
     SEND-PR: Choose from the following categories:
     SEND-PR:
     SEND-PR:           bfd       binutils  bison
     SEND-PR: byacc     clib      config    cvs         diff
     SEND-PR: doc       emacs     flex      g++         gas
     SEND-PR: gcc       gdb       glob      gprof       grep
     SEND-PR: info      ispell    kerberos  ld          libg++
     SEND-PR: libiberty make      makeinfo  mas         newlib
     SEND-PR: other     patch     rcs       readline    send-pr
     SEND-PR: test      texindex  texinfo   texinfo.tex
     SEND-PR: bifrabulator  <---note: this one is fake
     SEND-PR:
     To: cygnus-bugs@cygnus.com
     Subject:
     From: jeffrey@imaginary.com
     Reply-To: jeffrey@imaginary.com
     X-send-pr-version: send-pr VERSION

     >Submitter-Id:  imaginary
     >Originator:    Jeffrey Osier
     >Organization:
     Imaginary Software, Ltd.
     >Confidential:  <[ no | yes ] (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](oneline)>
     >Release:       <release number or tag (one line)>
     >Environment:
              <machine, os, target, libraries (multiple lines)>
     System: SunOS imaginary.com 4.1.1 1 sun4
     Architecture: sun4

     >Description:
            <precise description of the problem (multiple lines)>
     >How-To-Repeat:
            <code/input/activities to reproduce (multiple lines)>
     >Fix:
     -----Emacs: *send-pr*   (send-pr Fill)----All------------------
     >Category: other[]

We know from past experience that we need to set certain information into each field, so we compile all the information we know about our problem. We have some sample code which we know should work, even though it doesn't, so we'll include that.  Below is the completed PR; we send this using C-c C-c.  (The comments have been truncated).

     SEND-PR: Lines starting with `SEND-PR' will be removed
     SEND-PR: automatically as well as all comments (the text
     SEND-PR: ...
     SEND-PR:
     To: cygnus-bugs@cygnus.com
     Subject: bifrabulator routines don't match
     From: jeffrey@imaginary.com
     Reply-To: jeffrey@imaginary.com
     X-send-pr-version: send-pr VERSION

     >Submitter-Id:  imaginary
     >Originator:    Jeffrey Osier
     >Organization:
     Imaginary Software, Ltd.
     >Confidential:  no
     >Synopsis:      bifrabulator routines don't match
     >Severity:      serious
     >Priority:      medium
     >Category:      bifrabulator
     >Class:         sw-bug
     >Release:       progressive-930101
     >Environment:
     System: SunOS imaginary.com 4.1.1 1 sun4
     Architecture: sun4 (SPARC)

     >Description:
        the following code I fed into the bifrabulator came back
        with a strange error.  apparently, the prestidigitation
        routine doesn't match with the whatsitsname in all cases.

     >How-To-Repeat:
        call the bifrabulator on the following code.
        code sample...

     >Fix:
     -----Emacs: *send-pr*   (send-pr Fill)----All------------------
     To send the problem report use: C-c C-c

We type C-c C-c, and off it goes.  Now, we depend on Cygnus Support to figure out the answer to our problem.

Soon afterward, we get the following message from Cygnus:

     From: gnats (GNATS management)
     Sender: gnats-admin
     Reply-To: hacker@cygnus.com
     To: jeffrey@imaginary.com
     Subject: Re: bifrabulator/1425: routines don't match

     Thank you very much for your problem report.
     It has the internal identification: g++/1425.
     The individual assigned to look at your bug is:  hacker
     (F.B. Hacker)

     Category: bifrabulator
     Responsible: hacker
     Synopsis: bifrabulator routines don't match
     Arrival-Date: Sat Feb 30 03:12:55 1993

This is our receipt that the bug has been accepted and forwarded to the responsible party.

A while later, we get the analysis:

     To:  jeffrey@imaginary.com
     From:  hacker@cygnus.com
     Subject:  Re: bifrabulator/1425: routines don't match
     Reply-To: hacker@cygnus.com

     Got your message, Jeff.  It seems that the bifrabulator was
     confusing the prestidigitation routines with the realitychecker
     when lexically parsing the whatsitsname.

     I'm working on robustisizing the bifrabulator now.

     How about lunch next week?
     --
     F.B. Hacker
     Cygnus Support, Mountain View, CA  415 903 1400
     #include <std-disclaimer.h>

About the same time, we get another message from Cygnus.

     From: hacker@cygnus.com
     To:  jeffrey@imaginary.com
     Subject:  Re: bifrabulator/1425: doesn't match prestidig
     Reply-To:  hacker@cygnus.com

                  `F.B. Hacker' changed the state to `analyzed'.

     State-Changed-From-To: open-analyzed
     State-Changed-By: hacker
     State-Changed-When: Fri Feb 31 1993 08:59:16 1993
     State-Changed-Why:
         figured out the problem, working on a patch this afternoon
     --
     F.B. Hacker
     Cygnus Support, Mountain View, CA  415 903 1400
     #include <std-disclaimer.h>

The bug has now been analyzed, and Cygnus is working on a solution.

Sometime later, we get more mail from F.B.:

     To:  jeffrey@imaginary.com
     From:  hacker@cygnus.com
     Subject:  Re: bifrabulator/1425: routines don't match
     Reply-To: hacker@cygnus.com

     There's a patch now that you can ftp over and check out.

     Hey, that joke you sent me was great!  The one about the
     strings walking into a bar...  my boss laughed for an hour!
     --
     F.B. Hacker
     Cygnus Support, Mountain View, CA  415 903 1400
     #include <std-disclaimer.h>

     From: hacker@cygnus.com
     To:  jeffrey@imaginary.com
     Subject:  Re: bifrabulator/1425: doesn't match prestidig
     Reply-To:  hacker@cygnus.com

                  `F.B. Hacker' changed the state to `feedback'.

     State-Changed-From-To: analyzed-feedback
     State-Changed-By: hacker
     State-Changed-When: Fri Feb 31 1993 23:43:16 1993
     State-Changed-Why:
         got the patch finished, notified Jeff at Imaginary Software
     --
     F.B. Hacker
     Cygnus Support, Mountain View, CA  415 903 1400
     #include <std-disclaimer.h>

The bug has gone into feedback status now, until we get the patch, install it and test it.  When everything tests well, we can mail F.B. back and tell him the bug's been fixed, and he can change the state of the PR from feedback to closed.

Following is a list of valid >Category: entries that are supported by Cygnus.

     [file categ.texi not included]

Installing send-pr on your system
*********************************

If you receive send-pr as part of a larger software distribution, it probably gets installed when the full distribution is installed.  If you are using GNATS at your site as well, you must decide where send-pr sends Problem Reports by default; see Setting a default SITE.

Installing send-pr by itself
============================

Install send-pr by following these steps (you may need root access in order to change the aliases file and to install send-pr):

  * Unpack the distribution into a directory which we refer to as SRCDIR.

  * Edit the file Makefile to reflect local conventions. Specifically, you should edit the variable prefix to alter the installation location.  The default is /usr/local.  All files are installed under prefix (see below).

  * Run

          make all install [ info ] [ install-info ] [ clean ]

     The targets mean the following:

     all
          Builds send-pr and install-sid

     install
          Installs the following:

          install-sid
          send-pr
               into PREFIX/bin

          send-pr.1
               into PREFIX/man/man1

          SITE
               the list of valid CATEGORIES for the Support Site from which you received send-pr, installed as PREFIX/lib/gnats/SITE

          send-pr.el
               into PREFIX/lib/emacs/lisp (If your main Emacs lisp repository is in a different directory from this, substitute that directory for PREFIX/lib/emacs/lisp.)

     info (optional)
          Builds send-pr.info from send-pr.texi

          (send-pr.info is included with this distribution)

     install-info (optional)
          Installs send-pr.info into PREFIX/info

     clean (optional)
          Removes all intermediary build files that can be rebuilt from source code

  * Run

          install-sid YOUR-SID

     where YOUR-SID is the identification code you received with send-pr.  send-pr automatically inserts this value into the template field >Submitter-Id:.  If you've downloaded send-pr from the Net, use net for this value.

  * Place the following line in PREFIX/lib/emacs/lisp/default.el, or instruct your users to place the following line in their .emacs files:

          (autoload 'send-pr "send-pr" "Submit a Problem Report." t)

  * Create a mail alias for the Support Site from which you received send-pr, and for every site with which you wish to use send-pr to communicate.  Each alias must have a suffix of -gnats.  The Support Site(s) will provide the correct addresses where these aliases should point.  For instance, edit your mail aliases file to contain something like:

          # support sites; for use with send-pr
          cygnus-gnats:     bugs@cygnus.com            # Cygnus Support
          bumblebee-gnats:  bumblebugs@bumblebee.com   # Bumblebee Inc.
          mycompany-gnats:  bugs@my.company.com (if you use GNATS locally)

     send-pr automatically searches for these aliases when you type

          send-pr cygnus
          send-pr bumblebee
          send-pr SITE...

     send-pr also uses SITE to determine the categories of problems accepted by the site in question by looking in

          PREFIX/lib/gnats/SITE

Setting a default SITE
======================

send-pr is capable of sending Problem Reports to any number of Support Sites, using mail aliases which have -gnats appended them. send-pr automatically appends the suffix, so that when you type

     send-pr SITE

the Problem Report goes to the address noted in the aliases file as SITE-gnats.  You can do this in the Emacs version of send-pr by invoking the program with

     C-u M-x send-pr

You are prompted for SITE.

SITE is also used to error-check the >Category: field, as a precaution against sending mistaken information (and against sending information to the wrong site).

You may also simply type

     send-pr

from the shell (or M-x send-pr in Emacs), and the Problem Report you generate will be sent to the SITE, which is usually the site from which you received your distribution of send-pr. If you use GNATS at your own organization, the default is usually your local address for reporting problems.

To change this, simply edit the file Makefile before installing and change the line

     GNATS_SITE = SITE

to reflect the site where you wish to send PRs by default.