diff options
Diffstat (limited to 'gnu/usr.bin/send-pr/send-pr.texi')
| -rw-r--r-- | gnu/usr.bin/send-pr/send-pr.texi | 657 |
1 files changed, 657 insertions, 0 deletions
diff --git a/gnu/usr.bin/send-pr/send-pr.texi b/gnu/usr.bin/send-pr/send-pr.texi new file mode 100644 index 0000000..b9edd9c --- /dev/null +++ b/gnu/usr.bin/send-pr/send-pr.texi @@ -0,0 +1,657 @@ +\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:: Reporting problems--using send-pr +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@ifinfo +Copyright @copyright{} 1993 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 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 Support +@cindex GNU software support + +Cygnus Support in Mountain View, 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 Support 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 Support, 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: <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: +@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 Support, Mountain View, CA 415 903 1400 +#include <std-disclaimer.h> +@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 Support, Mountain View, CA 415 903 1400 +#include <std-disclaimer.h> +@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 Support, Mountain View, CA 415 903 1400 +#include <std-disclaimer.h> +@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 Support, Mountain View, CA 415 903 1400 +#include <std-disclaimer.h> +@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}/lib/gnats/@var{site}}} + +@item send-pr.el +into @w{@file{@var{prefix}/lib/emacs/lisp}}@footnote{If your main Emacs +lisp repository is in a different directory from this, substitute that +directory for @w{@file{@var{prefix}/lib/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}/lib/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 Support +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}/lib/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 |
