3 \input texinfo @c -*-texinfo-*-
4 @setfilename send-pr.info
5 @settitle Reporting Problems Using send-pr
15 * send-pr: (send-pr). Reporting problems--using send-pr
21 Copyright @copyright{} 1993, 1994, 1995 Free Software Foundation, Inc.
23 Permission is granted to make and distribute verbatim copies of
24 this manual provided the copyright notice and this permission notice
25 are preserved on all copies.
28 Permission is granted to process this file through TeX and print the
29 results, provided the printed document carries a copying permission
30 notice identical to this one except for the removal of this paragraph
31 (this paragraph not being relevant to the printed manual).
35 Permission is granted to copy and distribute modified versions of this
36 manual under the conditions for verbatim copying, provided also that
37 the entire resulting derived work is distributed under the terms of a
38 permission notice identical to this one.
40 Permission is granted to copy and distribute translations of this manual
41 into another language, under the above conditions for modified versions.
46 @title Reporting Problems
47 @subtitle Using @code{send-pr}, version @value{VERSION}
48 @subtitle October 1993
49 @author Jeffrey M. Osier
50 @author Cygnus Support
53 @vskip 0pt plus 1filll
55 Copyright @copyright{} 1993, 1994, 1995 Free Software Foundation, Inc.
57 Permission is granted to make and distribute verbatim copies of
58 this manual provided the copyright notice and this permission notice
59 are preserved on all copies.
61 Permission is granted to copy and distribute modified versions of this
62 manual under the conditions for verbatim copying, provided also that
63 the entire resulting derived work is distributed under the terms of a
64 permission notice identical to this one.
66 Permission is granted to copy and distribute translations of this manual
67 into another language, under the above conditions for modified versions.
71 @c ---------------------------------------------------------------
74 @cindex foreword to @code{send-pr}
75 @cindex overview to @code{send-pr}
76 @cindex introduction to @code{send-pr}
78 This manual documents @code{send-pr},
80 version @value{VERSION},
82 which uses electronic mail to submit support questions and problem
83 reports to a central Support Site. No body of work is perfect, and
84 support organizations understand this; @code{send-pr} is designed to
85 allow users who have problems to submit reports of these problems to
86 sites responsible for supporting the products in question, in a defined
87 form which can be read by an electronically managed database.
90 @code{send-pr} is part of a suite of programs known collectively as
91 @sc{gnats}, the @sc{gnu} Problem Report Management System. @sc{gnats}
92 consists of several programs which, used in concert, formulate and
93 partially administer a database of @dfn{Problem Reports}, or @dfn{PRs},
94 at a central Support Site. A PR goes through several states in its
95 lifetime; @sc{gnats} tracks the PR and all information associated with it
96 through each state and finally acts as an archive for PRs which have
99 Because @code{send-pr} exists as a shell (@file{/bin/sh}) script and as
100 an Elisp file for use with @sc{gnu} Emacs, it can be used from any
101 machine on your network which can run a shell script and/or Emacs.
103 In general, you can use any editor and mailer to submit valid Problem
104 Reports, as long as the format required by @sc{gnats} is preserved.
105 @code{send-pr} automates the process, however, and ensures that certain
106 fields necessary for automatic processing are present. @code{send-pr}
107 is strongly recommended for all initial problem-oriented correspondence
108 with your Support Site. The organization you submit Problem Reports to
109 supplies an address to which further information can be sent; the person
110 responsible for the category of the problem you report contacts you
114 * send-pr in detail:: Details about send-pr and GNATS
115 * Invoking send-pr:: Editing and sending PRs
116 * An Example:: A working example
117 * Installing send-pr:: Installing send-pr on your system
121 @node send-pr in detail
122 @chapter Details about send-pr and GNATS
124 @cindex details about @code{send-pr}
125 @cindex Problem Reports
126 A @dfn{Problem Report} is a message that describes a problem you are
127 having with a body of work. @code{send-pr} organizes this message into
128 a form which can be understood and automatically processed by @sc{gnats},
129 the @sc{gnu} Problem Report Management System. A Problem Report is
130 organized into @dfn{fields} which contain data describing you, your
131 organization, and the problem you are announcing (@pxref{Fields,,Problem
132 Report format}). Problem Reports go through several defined states in
133 their lifetimes, from @dfn{open} to @dfn{closed} (@pxref{States,,States
134 of Problem Reports}).
137 * States:: States of Problem Reports
138 * Fields:: Problem Report format
145 @node Invoking send-pr
146 @chapter Editing and sending PRs
147 @cindex editing and sending PRs
149 @cindex invoking send-pr
150 @cindex using send-pr
151 @cindex generating new PRs
153 @include s-usage.texi
159 @cindex Cygnus Solutions
160 @cindex @sc{gnu} software support
161 Cygnus Solutions in Sunnyvale, CA, uses @sc{gnats} and @code{send-pr}
162 extensively for their support activities. As a support company, Cygnus
163 finds problem tracking to be a crucial part of everyday business.
164 Cygnus supports the @sc{gnu} compiling tools (including @sc{gnats} and
165 @code{send-pr}) over several many platforms
167 With each shipment of the Cygnus Solutions Developer's Kit, customers
168 receive the latest version of @code{send-pr}, which contains an
169 up-to-date listing of valid categories (values for the @code{>Category:}
170 field). Using these tools, Cygnus' customers can communicate their
171 problems to Cygnus effectively and receive automatic confirmation of
172 receipt as well as notification of changes in the status of their
173 reported problems. Much of Cygnus' support mechanism relies on
176 As an example, let's pretend we're a customer of Cygnus Solutions, and
177 that we're having a problem compiling some of our software using the
178 @sc{gnu} C compiler, which Cygnus supports.
180 Assume that we're getting an error in our @code{bifrabulator} program
181 wherein the @samp{prestidigitation} routines don't match with the
182 @samp{whatsitsname}. We've made sure we're following the rules of the
183 program and checked the Release Notes from Cygnus and found that the bug
184 isn't already known. In other words, we're pretty sure we've found a
187 @cindex Imaginary Software, Ltd.
188 Our first step is to call @code{send-pr}. It really doesn't matter
189 whether we use @code{send-pr} from the shell or from within Emacs.
190 Indeed, if we use Emacs as a primary editor, calling @code{send-pr} from
191 the shell is likely to start @code{send-pr} in an Emacs buffer anyway.
192 So, since our company, @emph{Imaginary Software, Ltd.}, uses @sc{gnu}
193 software extensively, we're pretty familiar with Emacs, so from within
199 and we're greeted with the following screen:
201 @cindex default PR template
202 @cindex example of a default template
203 @cindex blank PR template
204 @cindex @code{bifrabulator}
207 SEND-PR: -*- text -*-
208 SEND-PR: Lines starting with `SEND-PR' will be removed
209 SEND-PR: automatically as well as all comments (the text
210 SEND-PR: below enclosed in `<' and `>').
211 SEND-PR: Please consult the manual if you are not sure
212 SEND-PR: how to fill out a problem report.
214 SEND-PR: Choose from the following categories:
216 SEND-PR: bfd binutils bison
217 SEND-PR: byacc clib config cvs diff
218 SEND-PR: doc emacs flex g++ gas
219 SEND-PR: gcc gdb glob gprof grep
220 SEND-PR: info ispell kerberos ld libg++
221 SEND-PR: libiberty make makeinfo mas newlib
222 SEND-PR: other patch rcs readline send-pr
223 SEND-PR: test texindex texinfo texinfo.tex
224 SEND-PR: bifrabulator <---@emph{note: this one is fake}
226 To: cygnus-bugs@@cygnus.com
228 From: jeffrey@@imaginary.com
229 Reply-To: jeffrey@@imaginary.com
230 X-send-pr-version: send-pr @value{VERSION}
232 >Submitter-Id: imaginary
233 >Originator: Jeffrey Osier
235 Imaginary Software, Ltd.
236 >Confidential: <[ yes | no ] (one line)>
237 >Synopsis: <synopsis of the problem (one line)>
238 >Severity: <[ non-critical | serious | critical ] (one line)>
239 >Priority: <[ low | medium | high ] (one line)>
240 >Category: <name of the product (one line)>
241 >Class: <[sw-bug|doc-bug|change-request|support](oneline)>
242 >Release: <release number or tag (one line)>
244 <machine, os, target, libraries (multiple lines)>
245 System: SunOS imaginary.com 4.1.1 1 sun4
249 <precise description of the problem (multiple lines)>
251 <code/input/activities to reproduce (multiple lines)>
256 -----Emacs: *send-pr* (send-pr Fill)----All------------------
264 We know from past experience that we need to set certain information into
265 each field, so we compile all the information we know about our problem.
266 We have some sample code which we know should work, even though it
267 doesn't, so we'll include that. Below is the completed PR; we send this
268 using @kbd{C-c C-c}. (The comments have been truncated).
270 @cindex completed Problem Report
271 @cindex example of a completed PR
274 SEND-PR: Lines starting with `SEND-PR' will be removed
275 SEND-PR: automatically as well as all comments (the text
278 To: cygnus-bugs@@cygnus.com
279 Subject: bifrabulator routines don't match
280 From: jeffrey@@imaginary.com
281 Reply-To: jeffrey@@imaginary.com
282 X-send-pr-version: send-pr @value{VERSION}
284 >Submitter-Id: imaginary
285 >Originator: Jeffrey Osier
287 Imaginary Software, Ltd.
289 >Synopsis: bifrabulator routines don't match
292 >Category: bifrabulator
294 >Release: progressive-930101
296 System: SunOS imaginary.com 4.1.1 1 sun4
297 Architecture: sun4 (SPARC)
300 the following code I fed into the bifrabulator came back
301 with a strange error. apparently, the prestidigitation
302 routine doesn't match with the whatsitsname in all cases.
305 call the bifrabulator on the following code.
306 @emph{code sample@dots{}}
312 -----Emacs: *send-pr* (send-pr Fill)----All------------------
316 To send the problem report use: C-c C-c
320 We type @kbd{C-c C-c}, and off it goes. Now, we depend on Cygnus
321 Support to figure out the answer to our problem.
323 Soon afterward, we get the following message from Cygnus:
327 From: gnats (GNATS management)
329 Reply-To: hacker@@cygnus.com
330 To: jeffrey@@imaginary.com
331 Subject: Re: bifrabulator/1425: routines don't match
333 Thank you very much for your problem report.
334 It has the internal identification: g++/1425.
335 The individual assigned to look at your bug is: hacker
338 Category: bifrabulator
340 Synopsis: bifrabulator routines don't match
341 Arrival-Date: Sat Feb 30 03:12:55 1993
346 This is our receipt that the bug has been accepted and forwarded to the
350 A while later, we get the analysis:
354 To: jeffrey@@imaginary.com
355 From: hacker@@cygnus.com
356 Subject: Re: bifrabulator/1425: routines don't match
357 Reply-To: hacker@@cygnus.com
359 Got your message, Jeff. It seems that the bifrabulator was
360 confusing the prestidigitation routines with the realitychecker
361 when lexically parsing the whatsitsname.
363 I'm working on robustisizing the bifrabulator now.
365 How about lunch next week?
368 Cygnus Solutions, Sunnyvale, CA 408 542 9600
369 #include <std-disclaimer.h>
374 About the same time, we get another message from Cygnus.
376 @cindex state change example
377 @cindex example of a state change
380 From: hacker@@cygnus.com
381 To: jeffrey@@imaginary.com
382 Subject: Re: bifrabulator/1425: doesn't match prestidig
383 Reply-To: hacker@@cygnus.com
386 `F.B. Hacker' changed the state to `analyzed'.
388 State-Changed-From-To: open-analyzed
389 State-Changed-By: hacker
390 State-Changed-When: Fri Feb 31 1993 08:59:16 1993
392 figured out the problem, working on a patch this afternoon
395 Cygnus Solutions, Sunnyvale, CA 408 542 9600
396 #include <std-disclaimer.h>
401 The bug has now been analyzed, and Cygnus is working on a solution.
404 Sometime later, we get more mail from F.B.:
408 To: jeffrey@@imaginary.com
409 From: hacker@@cygnus.com
410 Subject: Re: bifrabulator/1425: routines don't match
411 Reply-To: hacker@@cygnus.com
413 There's a patch now that you can ftp over and check out.
415 Hey, that joke you sent me was great! The one about the
416 strings walking into a bar... my boss laughed for an hour!
419 Cygnus Solutions, Sunnyvale, CA 408 542 9600
420 #include <std-disclaimer.h>
426 From: hacker@@cygnus.com
427 To: jeffrey@@imaginary.com
428 Subject: Re: bifrabulator/1425: doesn't match prestidig
429 Reply-To: hacker@@cygnus.com
432 `F.B. Hacker' changed the state to `feedback'.
434 State-Changed-From-To: analyzed-feedback
435 State-Changed-By: hacker
436 State-Changed-When: Fri Feb 31 1993 23:43:16 1993
438 got the patch finished, notified Jeff at Imaginary Software
441 Cygnus Solutions, Sunnyvale, CA 408 542 9600
442 #include <std-disclaimer.h>
447 The bug has gone into @dfn{feedback} status now, until we get the patch,
448 install it and test it. When everything tests well, we can mail F.B.
449 back and tell him the bug's been fixed, and he can change the state of
450 the PR from @dfn{feedback} to @dfn{closed}.
452 Following is a list of valid @samp{>Category:} entries that are
459 @c FIXME - is this list up to date?
462 @node Installing send-pr
463 @appendix Installing @code{send-pr} on your system
466 If you receive @code{send-pr} as part of a larger software distribution,
467 it probably gets installed when the full distribution is installed. If
468 you are using @sc{gnats} at your site as well, you must decide where
469 @code{send-pr} sends Problem Reports by default; see @ref{default site,,
470 Setting a default @var{site}}.
473 * installation:: installing `send-pr' by itself
474 * default site:: setting a default site
478 @section Installing @code{send-pr} by itself
479 @cindex installation procedure
481 Install @code{send-pr} by following these steps (you may need
482 @code{root} access in order to change the @file{aliases} file and to
483 install @code{send-pr}):
487 Unpack the distribution into a directory which we refer to as
491 Edit the file @file{Makefile} to reflect local conventions.
492 Specifically, you should edit the variable @samp{prefix} to alter the
493 installation location. The default is @file{/usr/local}. All files are
494 installed under @samp{prefix} (see below).
498 make all install [ info ] [ install-info ] [ clean ]
502 The targets mean the following:
506 Builds @code{send-pr} and @code{install-sid}
509 Installs the following:
514 into @file{@var{prefix}/bin}
517 into @file{@var{prefix}/man/man1}
520 the list of valid @var{categories} for the Support Site from which you
521 received @code{send-pr}, installed as
522 @w{@file{@var{prefix}/share/gnats/@var{site}}}
525 into @w{@file{@var{prefix}/share/emacs/lisp}}@footnote{If your main Emacs
526 lisp repository is in a different directory from this, substitute that
527 directory for @w{@file{@var{prefix}/share/emacs/lisp}}.}
530 @item info (@emph{optional})
531 Builds @file{send-pr.info} from @file{send-pr.texi}@*
532 @c FIXME - is this still true?
533 (@file{send-pr.info} is included with this distribution)
535 @item install-info (@emph{optional})
536 Installs @file{send-pr.info} into @w{@file{@var{prefix}/info}}
538 @item clean (@emph{optional})
539 Removes all intermediary build files that can be rebuilt from source
547 install-sid @var{your-sid}
551 where @var{your-sid} is the identification code you received with
552 @w{@code{send-pr}}. @code{send-pr} automatically inserts this value
553 into the template field @samp{>Submitter-Id:}. If you've downloaded
554 @code{send-pr} from the Net, use @samp{net} for this value.
557 Place the following line in
558 @w{@file{@var{prefix}/share/emacs/lisp/default.el}}, or instruct your
559 users to place the following line in their @file{.emacs} files:
562 (autoload 'send-pr "send-pr" "Submit a Problem Report." t)
566 Create a mail alias for the Support Site from which you received
567 @code{send-pr}, and for every site with which you wish to use
568 @code{send-pr} to communicate. Each alias must have a suffix of
569 @samp{-gnats}. The Support Site(s) will provide the correct addresses
570 where these aliases should point. For instance, edit your mail aliases
571 file to contain something like:
574 # support sites; for use with send-pr
575 cygnus-gnats: bugs@@cygnus.com # Cygnus Solutions
576 bumblebee-gnats: bumblebugs@@bumblebee.com # Bumblebee Inc.
577 mycompany-gnats: bugs@@my.company.com (@emph{if you use @sc{gnats} locally})
580 @code{send-pr} automatically searches for these aliases when you type
585 send-pr @var{site}@dots{}
589 @code{send-pr} also uses @var{site} to determine the categories of
590 problems accepted by the site in question by looking in
593 @var{prefix}/share/gnats/@var{site}
599 @section Setting a default @var{site}
600 @cindex default @var{site}
601 @cindex setting a default @var{site}
603 @code{send-pr} is capable of sending Problem Reports to any number of
604 Support Sites, using mail aliases which have @samp{-gnats} appended them.
605 @code{send-pr} automatically appends the suffix, so that when you type
612 the Problem Report goes to the address noted in the @file{aliases} file
613 as @w{@samp{@var{site}-gnats}}. You can do this in the Emacs version of
614 @code{send-pr} by invoking the program with
621 You are prompted for @var{site}.
623 @var{site} is also used to error-check the @samp{>Category:} field, as a
624 precaution against sending mistaken information (and against sending
625 information to the wrong site).
627 You may also simply type
634 from the shell (or @w{@samp{M-x send-pr}} in Emacs), and the Problem
635 Report you generate will be sent to the @var{site}, which is usually the
636 site from which you received your distribution of @w{@code{send-pr}}.
637 If you use @sc{gnats} at your own organization, the default is usually
638 your local address for reporting problems.
640 To change this, simply edit the file @file{Makefile} before installing
644 GNATS_SITE = @var{site}
648 to reflect the site where you wish to send PRs by default.
650 @c ---------------------------------------------------------------
656 @c ---------------------------------------------------------------