@c $FreeBSD$ \input texinfo @c -*-texinfo-*- @setfilename send-pr.info @settitle Reporting Problems Using send-pr @setchapternewpage odd @include version.texi @set SENDPR @ifinfo @format START-INFO-DIR-ENTRY * send-pr: (send-pr). Reporting problems--using send-pr END-INFO-DIR-ENTRY @end format @end ifinfo @ifinfo Copyright @copyright{} 1993, 1994, 1995 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. @ignore Permission is granted to process this file through TeX and print the results, provided the printed document carries a copying permission notice identical to this one except for the removal of this paragraph (this paragraph not being relevant to the printed manual). @end ignore 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. @end ifinfo @titlepage @finalout @title Reporting Problems @subtitle Using @code{send-pr}, version @value{VERSION} @subtitle October 1993 @author Jeffrey M. Osier @author Cygnus Support @page @vskip 0pt plus 1filll Copyright @copyright{} 1993, 1994, 1995 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. @end titlepage @c --------------------------------------------------------------- @node Top @top Overview @cindex foreword to @code{send-pr} @cindex overview to @code{send-pr} @cindex introduction to @code{send-pr} This manual documents @code{send-pr}, @ifinfo version @value{VERSION}, @end ifinfo 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; @code{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. @cindex GNATS @code{send-pr} is part of a suite of programs known collectively as @sc{gnats}, the @sc{gnu} Problem Report Management System. @sc{gnats} consists of several programs which, used in concert, formulate and partially administer a database of @dfn{Problem Reports}, or @dfn{PRs}, at a central Support Site. A PR goes through several states in its lifetime; @sc{gnats} tracks the PR and all information associated with it through each state and finally acts as an archive for PRs which have been @dfn{closed}. Because @code{send-pr} exists as a shell (@file{/bin/sh}) script and as an Elisp file for use with @sc{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 @sc{gnats} is preserved. @code{send-pr} automates the process, however, and ensures that certain fields necessary for automatic processing are present. @code{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. @menu * send-pr in detail:: Details about send-pr and GNATS * Invoking send-pr:: Editing and sending PRs * An Example:: A working example * Installing send-pr:: Installing send-pr on your system * Index:: @end menu @node send-pr in detail @chapter Details about send-pr and GNATS @cindex details about @code{send-pr} @cindex Problem Reports A @dfn{Problem Report} is a message that describes a problem you are having with a body of work. @code{send-pr} organizes this message into a form which can be understood and automatically processed by @sc{gnats}, the @sc{gnu} Problem Report Management System. A Problem Report is organized into @dfn{fields} which contain data describing you, your organization, and the problem you are announcing (@pxref{Fields,,Problem Report format}). Problem Reports go through several defined states in their lifetimes, from @dfn{open} to @dfn{closed} (@pxref{States,,States of Problem Reports}). @menu * States:: States of Problem Reports * Fields:: Problem Report format @end menu @include states.texi @include fields.texi @node Invoking send-pr @chapter Editing and sending PRs @cindex editing and sending PRs @cindex sending PRs @cindex invoking send-pr @cindex using send-pr @cindex generating new PRs @include s-usage.texi @node An Example @chapter An Example @cindex an example @cindex example PR @cindex Cygnus Solutions @cindex @sc{gnu} software support Cygnus Solutions in Sunnyvale, CA, uses @sc{gnats} and @code{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 @sc{gnu} compiling tools (including @sc{gnats} and @code{send-pr}) over several many platforms With each shipment of the Cygnus Solutions Developer's Kit, customers receive the latest version of @code{send-pr}, which contains an up-to-date listing of valid categories (values for the @code{>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 Solutions, and that we're having a problem compiling some of our software using the @sc{gnu} C compiler, which Cygnus supports. Assume that we're getting an error in our @code{bifrabulator} program wherein the @samp{prestidigitation} routines don't match with the @samp{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. @cindex Imaginary Software, Ltd. Our first step is to call @code{send-pr}. It really doesn't matter whether we use @code{send-pr} from the shell or from within Emacs. Indeed, if we use Emacs as a primary editor, calling @code{send-pr} from the shell is likely to start @code{send-pr} in an Emacs buffer anyway. So, since our company, @emph{Imaginary Software, Ltd.}, uses @sc{gnu} software extensively, we're pretty familiar with Emacs, so from within Emacs we type @smallexample M-x send-pr @end smallexample @noindent and we're greeted with the following screen: @cindex default PR template @cindex example of a default template @cindex blank PR template @cindex @code{bifrabulator} @cartouche @smallexample 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 <---@emph{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 @value{VERSION} >Submitter-Id: imaginary >Originator: Jeffrey Osier >Organization: Imaginary Software, Ltd. >Confidential: <[ yes | no ] (one line)> >Synopsis: >Severity: <[ non-critical | serious | critical ] (one line)> >Priority: <[ low | medium | high ] (one line)> >Category: >Class: <[sw-bug|doc-bug|change-request|support](oneline)> >Release: >Environment: System: SunOS imaginary.com 4.1.1 1 sun4 Architecture: sun4 >Description: >How-To-Repeat: >Fix: @iftex @hrule @end iftex -----Emacs: *send-pr* (send-pr Fill)----All------------------ @iftex @hrule @end iftex >Category: other[] @end smallexample @end cartouche @page 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 @kbd{C-c C-c}. (The comments have been truncated). @cindex completed Problem Report @cindex example of a completed PR @cartouche @smallexample SEND-PR: Lines starting with `SEND-PR' will be removed SEND-PR: automatically as well as all comments (the text SEND-PR: @dots{} 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 @value{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. @emph{code sample@dots{}} >Fix: @iftex @hrule @end iftex -----Emacs: *send-pr* (send-pr Fill)----All------------------ @iftex @hrule @end iftex To send the problem report use: C-c C-c @end smallexample @end cartouche We type @kbd{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: @smallexample @group 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 @end group @end smallexample @noindent This is our receipt that the bug has been accepted and forwarded to the responsible party. @noindent A while later, we get the analysis: @smallexample @group 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 Solutions, Sunnyvale, CA 408 542 9600 #include @end group @end smallexample @noindent About the same time, we get another message from Cygnus. @cindex state change example @cindex example of a state change @smallexample @group 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 Solutions, Sunnyvale, CA 408 542 9600 #include @end group @end smallexample @noindent The bug has now been analyzed, and Cygnus is working on a solution. @noindent Sometime later, we get more mail from F.B.: @smallexample @group 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 Solutions, Sunnyvale, CA 408 542 9600 #include @end group @end smallexample @sp 2 @smallexample @group 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 Solutions, Sunnyvale, CA 408 542 9600 #include @end group @end smallexample @noindent The bug has gone into @dfn{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 @dfn{feedback} to @dfn{closed}. Following is a list of valid @samp{>Category:} entries that are supported by Cygnus. @menu * Valid Categories:: @end menu @c FIXME - is this list up to date? @include categ.texi @node Installing send-pr @appendix Installing @code{send-pr} on your system @cindex installation If you receive @code{send-pr} as part of a larger software distribution, it probably gets installed when the full distribution is installed. If you are using @sc{gnats} at your site as well, you must decide where @code{send-pr} sends Problem Reports by default; see @ref{default site,, Setting a default @var{site}}. @menu * installation:: installing `send-pr' by itself * default site:: setting a default site @end menu @node installation @section Installing @code{send-pr} by itself @cindex installation procedure Install @code{send-pr} by following these steps (you may need @code{root} access in order to change the @file{aliases} file and to install @code{send-pr}): @itemize @bullet @item Unpack the distribution into a directory which we refer to as @var{srcdir}. @item Edit the file @file{Makefile} to reflect local conventions. Specifically, you should edit the variable @samp{prefix} to alter the installation location. The default is @file{/usr/local}. All files are installed under @samp{prefix} (see below). @item @emph{Run} @smallexample make all install [ info ] [ install-info ] [ clean ] @end smallexample @noindent The targets mean the following: @table @code @item all Builds @code{send-pr} and @code{install-sid} @item install Installs the following: @table @code @item install-sid @itemx send-pr into @file{@var{prefix}/bin} @item send-pr.1 into @file{@var{prefix}/man/man1} @item @var{site} the list of valid @var{categories} for the Support Site from which you received @code{send-pr}, installed as @w{@file{@var{prefix}/share/gnats/@var{site}}} @item send-pr.el into @w{@file{@var{prefix}/share/emacs/lisp}}@footnote{If your main Emacs lisp repository is in a different directory from this, substitute that directory for @w{@file{@var{prefix}/share/emacs/lisp}}.} @end table @item info (@emph{optional}) Builds @file{send-pr.info} from @file{send-pr.texi}@* @c FIXME - is this still true? (@file{send-pr.info} is included with this distribution) @item install-info (@emph{optional}) Installs @file{send-pr.info} into @w{@file{@var{prefix}/info}} @item clean (@emph{optional}) Removes all intermediary build files that can be rebuilt from source code @end table @item Run @smallexample install-sid @var{your-sid} @end smallexample @noindent where @var{your-sid} is the identification code you received with @w{@code{send-pr}}. @code{send-pr} automatically inserts this value into the template field @samp{>Submitter-Id:}. If you've downloaded @code{send-pr} from the Net, use @samp{net} for this value. @item Place the following line in @w{@file{@var{prefix}/share/emacs/lisp/default.el}}, or instruct your users to place the following line in their @file{.emacs} files: @smallexample (autoload 'send-pr "send-pr" "Submit a Problem Report." t) @end smallexample @item Create a mail alias for the Support Site from which you received @code{send-pr}, and for every site with which you wish to use @code{send-pr} to communicate. Each alias must have a suffix of @samp{-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: @smallexample # support sites; for use with send-pr cygnus-gnats: bugs@@cygnus.com # Cygnus Solutions bumblebee-gnats: bumblebugs@@bumblebee.com # Bumblebee Inc. mycompany-gnats: bugs@@my.company.com (@emph{if you use @sc{gnats} locally}) @end smallexample @code{send-pr} automatically searches for these aliases when you type @smallexample send-pr cygnus send-pr bumblebee send-pr @var{site}@dots{} @end smallexample @noindent @code{send-pr} also uses @var{site} to determine the categories of problems accepted by the site in question by looking in @smallexample @var{prefix}/share/gnats/@var{site} @end smallexample @end itemize @node default site @section Setting a default @var{site} @cindex default @var{site} @cindex setting a default @var{site} @code{send-pr} is capable of sending Problem Reports to any number of Support Sites, using mail aliases which have @samp{-gnats} appended them. @code{send-pr} automatically appends the suffix, so that when you type @smallexample send-pr @var{site} @end smallexample @noindent the Problem Report goes to the address noted in the @file{aliases} file as @w{@samp{@var{site}-gnats}}. You can do this in the Emacs version of @code{send-pr} by invoking the program with @smallexample C-u M-x send-pr @end smallexample @noindent You are prompted for @var{site}. @var{site} is also used to error-check the @samp{>Category:} field, as a precaution against sending mistaken information (and against sending information to the wrong site). You may also simply type @smallexample send-pr @end smallexample @noindent from the shell (or @w{@samp{M-x send-pr}} in Emacs), and the Problem Report you generate will be sent to the @var{site}, which is usually the site from which you received your distribution of @w{@code{send-pr}}. If you use @sc{gnats} at your own organization, the default is usually your local address for reporting problems. To change this, simply edit the file @file{Makefile} before installing and change the line @smallexample GNATS_SITE = @var{site} @end smallexample @noindent to reflect the site where you wish to send PRs by default. @c --------------------------------------------------------------- @node Index @unnumbered Index @printindex cp @c --------------------------------------------------------------- @contents @bye