1 \input texinfo @c -*-texinfo-*-
2 @setfilename send-pr.info
3 @settitle Reporting Problems Using send-pr
13 * send-pr: (send-pr). Reporting problems--using send-pr
19 Copyright @copyright{} 1993, 1994, 1995 Free Software Foundation, Inc.
21 Permission is granted to make and distribute verbatim copies of
22 this manual provided the copyright notice and this permission notice
23 are preserved on all copies.
26 Permission is granted to process this file through TeX and print the
27 results, provided the printed document carries a copying permission
28 notice identical to this one except for the removal of this paragraph
29 (this paragraph not being relevant to the printed manual).
33 Permission is granted to copy and distribute modified versions of this
34 manual under the conditions for verbatim copying, provided also that
35 the entire resulting derived work is distributed under the terms of a
36 permission notice identical to this one.
38 Permission is granted to copy and distribute translations of this manual
39 into another language, under the above conditions for modified versions.
44 @title Reporting Problems
45 @subtitle Using @code{send-pr}, version @value{VERSION}
46 @subtitle October 1993
47 @author Jeffrey M. Osier
48 @author Cygnus Support
51 @vskip 0pt plus 1filll
53 Copyright @copyright{} 1993, 1994, 1995 Free Software Foundation, Inc.
55 Permission is granted to make and distribute verbatim copies of
56 this manual provided the copyright notice and this permission notice
57 are preserved on all copies.
59 Permission is granted to copy and distribute modified versions of this
60 manual under the conditions for verbatim copying, provided also that
61 the entire resulting derived work is distributed under the terms of a
62 permission notice identical to this one.
64 Permission is granted to copy and distribute translations of this manual
65 into another language, under the above conditions for modified versions.
69 @c ---------------------------------------------------------------
72 @cindex foreword to @code{send-pr}
73 @cindex overview to @code{send-pr}
74 @cindex introduction to @code{send-pr}
76 This manual documents @code{send-pr},
78 version @value{VERSION},
80 which uses electronic mail to submit support questions and problem
81 reports to a central Support Site. No body of work is perfect, and
82 support organizations understand this; @code{send-pr} is designed to
83 allow users who have problems to submit reports of these problems to
84 sites responsible for supporting the products in question, in a defined
85 form which can be read by an electronically managed database.
88 @code{send-pr} is part of a suite of programs known collectively as
89 @sc{gnats}, the @sc{gnu} Problem Report Management System. @sc{gnats}
90 consists of several programs which, used in concert, formulate and
91 partially administer a database of @dfn{Problem Reports}, or @dfn{PRs},
92 at a central Support Site. A PR goes through several states in its
93 lifetime; @sc{gnats} tracks the PR and all information associated with it
94 through each state and finally acts as an archive for PRs which have
97 Because @code{send-pr} exists as a shell (@file{/bin/sh}) script and as
98 an Elisp file for use with @sc{gnu} Emacs, it can be used from any
99 machine on your network which can run a shell script and/or Emacs.
101 In general, you can use any editor and mailer to submit valid Problem
102 Reports, as long as the format required by @sc{gnats} is preserved.
103 @code{send-pr} automates the process, however, and ensures that certain
104 fields necessary for automatic processing are present. @code{send-pr}
105 is strongly recommended for all initial problem-oriented correspondence
106 with your Support Site. The organization you submit Problem Reports to
107 supplies an address to which further information can be sent; the person
108 responsible for the category of the problem you report contacts you
112 * send-pr in detail:: Details about send-pr and GNATS
113 * Invoking send-pr:: Editing and sending PRs
114 * An Example:: A working example
115 * Installing send-pr:: Installing send-pr on your system
119 @node send-pr in detail
120 @chapter Details about send-pr and GNATS
122 @cindex details about @code{send-pr}
123 @cindex Problem Reports
124 A @dfn{Problem Report} is a message that describes a problem you are
125 having with a body of work. @code{send-pr} organizes this message into
126 a form which can be understood and automatically processed by @sc{gnats},
127 the @sc{gnu} Problem Report Management System. A Problem Report is
128 organized into @dfn{fields} which contain data describing you, your
129 organization, and the problem you are announcing (@pxref{Fields,,Problem
130 Report format}). Problem Reports go through several defined states in
131 their lifetimes, from @dfn{open} to @dfn{closed} (@pxref{States,,States
132 of Problem Reports}).
135 * States:: States of Problem Reports
136 * Fields:: Problem Report format
143 @node Invoking send-pr
144 @chapter Editing and sending PRs
145 @cindex editing and sending PRs
147 @cindex invoking send-pr
148 @cindex using send-pr
149 @cindex generating new PRs
151 @include s-usage.texi
157 @cindex Cygnus Support
158 @cindex @sc{gnu} software support
159 Cygnus Support in Mountain View, CA, uses @sc{gnats} and @code{send-pr}
160 extensively for their support activities. As a support company, Cygnus
161 finds problem tracking to be a crucial part of everyday business.
162 Cygnus supports the @sc{gnu} compiling tools (including @sc{gnats} and
163 @code{send-pr}) over several many platforms
165 With each shipment of the Cygnus Support Developer's Kit, customers
166 receive the latest version of @code{send-pr}, which contains an
167 up-to-date listing of valid categories (values for the @code{>Category:}
168 field). Using these tools, Cygnus' customers can communicate their
169 problems to Cygnus effectively and receive automatic confirmation of
170 receipt as well as notification of changes in the status of their
171 reported problems. Much of Cygnus' support mechanism relies on
174 As an example, let's pretend we're a customer of Cygnus Support, and
175 that we're having a problem compiling some of our software using the
176 @sc{gnu} C compiler, which Cygnus supports.
178 Assume that we're getting an error in our @code{bifrabulator} program
179 wherein the @samp{prestidigitation} routines don't match with the
180 @samp{whatsitsname}. We've made sure we're following the rules of the
181 program and checked the Release Notes from Cygnus and found that the bug
182 isn't already known. In other words, we're pretty sure we've found a
185 @cindex Imaginary Software, Ltd.
186 Our first step is to call @code{send-pr}. It really doesn't matter
187 whether we use @code{send-pr} from the shell or from within Emacs.
188 Indeed, if we use Emacs as a primary editor, calling @code{send-pr} from
189 the shell is likely to start @code{send-pr} in an Emacs buffer anyway.
190 So, since our company, @emph{Imaginary Software, Ltd.}, uses @sc{gnu}
191 software extensively, we're pretty familiar with Emacs, so from within
197 and we're greeted with the following screen:
199 @cindex default PR template
200 @cindex example of a default template
201 @cindex blank PR template
202 @cindex @code{bifrabulator}
205 SEND-PR: -*- text -*-
206 SEND-PR: Lines starting with `SEND-PR' will be removed
207 SEND-PR: automatically as well as all comments (the text
208 SEND-PR: below enclosed in `<' and `>').
209 SEND-PR: Please consult the manual if you are not sure
210 SEND-PR: how to fill out a problem report.
212 SEND-PR: Choose from the following categories:
214 SEND-PR: bfd binutils bison
215 SEND-PR: byacc clib config cvs diff
216 SEND-PR: doc emacs flex g++ gas
217 SEND-PR: gcc gdb glob gprof grep
218 SEND-PR: info ispell kerberos ld libg++
219 SEND-PR: libiberty make makeinfo mas newlib
220 SEND-PR: other patch rcs readline send-pr
221 SEND-PR: test texindex texinfo texinfo.tex
222 SEND-PR: bifrabulator <---@emph{note: this one is fake}
224 To: cygnus-bugs@@cygnus.com
226 From: jeffrey@@imaginary.com
227 Reply-To: jeffrey@@imaginary.com
228 X-send-pr-version: send-pr @value{VERSION}
230 >Submitter-Id: imaginary
231 >Originator: Jeffrey Osier
233 Imaginary Software, Ltd.
234 >Confidential: <[ yes | no ] (one line)>
235 >Synopsis: <synopsis of the problem (one line)>
236 >Severity: <[ non-critical | serious | critical ] (one line)>
237 >Priority: <[ low | medium | high ] (one line)>
238 >Category: <name of the product (one line)>
239 >Class: <[sw-bug|doc-bug|change-request|support](oneline)>
240 >Release: <release number or tag (one line)>
242 <machine, os, target, libraries (multiple lines)>
243 System: SunOS imaginary.com 4.1.1 1 sun4
247 <precise description of the problem (multiple lines)>
249 <code/input/activities to reproduce (multiple lines)>
254 -----Emacs: *send-pr* (send-pr Fill)----All------------------
262 We know from past experience that we need to set certain information into
263 each field, so we compile all the information we know about our problem.
264 We have some sample code which we know should work, even though it
265 doesn't, so we'll include that. Below is the completed PR; we send this
266 using @kbd{C-c C-c}. (The comments have been truncated).
268 @cindex completed Problem Report
269 @cindex example of a completed PR
272 SEND-PR: Lines starting with `SEND-PR' will be removed
273 SEND-PR: automatically as well as all comments (the text
276 To: cygnus-bugs@@cygnus.com
277 Subject: bifrabulator routines don't match
278 From: jeffrey@@imaginary.com
279 Reply-To: jeffrey@@imaginary.com
280 X-send-pr-version: send-pr @value{VERSION}
282 >Submitter-Id: imaginary
283 >Originator: Jeffrey Osier
285 Imaginary Software, Ltd.
287 >Synopsis: bifrabulator routines don't match
290 >Category: bifrabulator
292 >Release: progressive-930101
294 System: SunOS imaginary.com 4.1.1 1 sun4
295 Architecture: sun4 (SPARC)
298 the following code I fed into the bifrabulator came back
299 with a strange error. apparently, the prestidigitation
300 routine doesn't match with the whatsitsname in all cases.
303 call the bifrabulator on the following code.
304 @emph{code sample@dots{}}
310 -----Emacs: *send-pr* (send-pr Fill)----All------------------
314 To send the problem report use: C-c C-c
318 We type @kbd{C-c C-c}, and off it goes. Now, we depend on Cygnus
319 Support to figure out the answer to our problem.
321 Soon afterward, we get the following message from Cygnus:
325 From: gnats (GNATS management)
327 Reply-To: hacker@@cygnus.com
328 To: jeffrey@@imaginary.com
329 Subject: Re: bifrabulator/1425: routines don't match
331 Thank you very much for your problem report.
332 It has the internal identification: g++/1425.
333 The individual assigned to look at your bug is: hacker
336 Category: bifrabulator
338 Synopsis: bifrabulator routines don't match
339 Arrival-Date: Sat Feb 30 03:12:55 1993
344 This is our receipt that the bug has been accepted and forwarded to the
348 A while later, we get the analysis:
352 To: jeffrey@@imaginary.com
353 From: hacker@@cygnus.com
354 Subject: Re: bifrabulator/1425: routines don't match
355 Reply-To: hacker@@cygnus.com
357 Got your message, Jeff. It seems that the bifrabulator was
358 confusing the prestidigitation routines with the realitychecker
359 when lexically parsing the whatsitsname.
361 I'm working on robustisizing the bifrabulator now.
363 How about lunch next week?
366 Cygnus Support, Mountain View, CA 415 903 1400
367 #include <std-disclaimer.h>
372 About the same time, we get another message from Cygnus.
374 @cindex state change example
375 @cindex example of a state change
378 From: hacker@@cygnus.com
379 To: jeffrey@@imaginary.com
380 Subject: Re: bifrabulator/1425: doesn't match prestidig
381 Reply-To: hacker@@cygnus.com
384 `F.B. Hacker' changed the state to `analyzed'.
386 State-Changed-From-To: open-analyzed
387 State-Changed-By: hacker
388 State-Changed-When: Fri Feb 31 1993 08:59:16 1993
390 figured out the problem, working on a patch this afternoon
393 Cygnus Support, Mountain View, CA 415 903 1400
394 #include <std-disclaimer.h>
399 The bug has now been analyzed, and Cygnus is working on a solution.
402 Sometime later, we get more mail from F.B.:
406 To: jeffrey@@imaginary.com
407 From: hacker@@cygnus.com
408 Subject: Re: bifrabulator/1425: routines don't match
409 Reply-To: hacker@@cygnus.com
411 There's a patch now that you can ftp over and check out.
413 Hey, that joke you sent me was great! The one about the
414 strings walking into a bar... my boss laughed for an hour!
417 Cygnus Support, Mountain View, CA 415 903 1400
418 #include <std-disclaimer.h>
424 From: hacker@@cygnus.com
425 To: jeffrey@@imaginary.com
426 Subject: Re: bifrabulator/1425: doesn't match prestidig
427 Reply-To: hacker@@cygnus.com
430 `F.B. Hacker' changed the state to `feedback'.
432 State-Changed-From-To: analyzed-feedback
433 State-Changed-By: hacker
434 State-Changed-When: Fri Feb 31 1993 23:43:16 1993
436 got the patch finished, notified Jeff at Imaginary Software
439 Cygnus Support, Mountain View, CA 415 903 1400
440 #include <std-disclaimer.h>
445 The bug has gone into @dfn{feedback} status now, until we get the patch,
446 install it and test it. When everything tests well, we can mail F.B.
447 back and tell him the bug's been fixed, and he can change the state of
448 the PR from @dfn{feedback} to @dfn{closed}.
450 Following is a list of valid @samp{>Category:} entries that are
457 @c FIXME - is this list up to date?
460 @node Installing send-pr
461 @appendix Installing @code{send-pr} on your system
464 If you receive @code{send-pr} as part of a larger software distribution,
465 it probably gets installed when the full distribution is installed. If
466 you are using @sc{gnats} at your site as well, you must decide where
467 @code{send-pr} sends Problem Reports by default; see @ref{default site,,
468 Setting a default @var{site}}.
471 * installation:: installing `send-pr' by itself
472 * default site:: setting a default site
476 @section Installing @code{send-pr} by itself
477 @cindex installation procedure
479 Install @code{send-pr} by following these steps (you may need
480 @code{root} access in order to change the @file{aliases} file and to
481 install @code{send-pr}):
485 Unpack the distribution into a directory which we refer to as
489 Edit the file @file{Makefile} to reflect local conventions.
490 Specifically, you should edit the variable @samp{prefix} to alter the
491 installation location. The default is @file{/usr/local}. All files are
492 installed under @samp{prefix} (see below).
496 make all install [ info ] [ install-info ] [ clean ]
500 The targets mean the following:
504 Builds @code{send-pr} and @code{install-sid}
507 Installs the following:
512 into @file{@var{prefix}/bin}
515 into @file{@var{prefix}/man/man1}
518 the list of valid @var{categories} for the Support Site from which you
519 received @code{send-pr}, installed as
520 @w{@file{@var{prefix}/lib/gnats/@var{site}}}
523 into @w{@file{@var{prefix}/lib/emacs/lisp}}@footnote{If your main Emacs
524 lisp repository is in a different directory from this, substitute that
525 directory for @w{@file{@var{prefix}/lib/emacs/lisp}}.}
528 @item info (@emph{optional})
529 Builds @file{send-pr.info} from @file{send-pr.texi}@*
530 @c FIXME - is this still true?
531 (@file{send-pr.info} is included with this distribution)
533 @item install-info (@emph{optional})
534 Installs @file{send-pr.info} into @w{@file{@var{prefix}/info}}
536 @item clean (@emph{optional})
537 Removes all intermediary build files that can be rebuilt from source
545 install-sid @var{your-sid}
549 where @var{your-sid} is the identification code you received with
550 @w{@code{send-pr}}. @code{send-pr} automatically inserts this value
551 into the template field @samp{>Submitter-Id:}. If you've downloaded
552 @code{send-pr} from the Net, use @samp{net} for this value.
555 Place the following line in
556 @w{@file{@var{prefix}/lib/emacs/lisp/default.el}}, or instruct your
557 users to place the following line in their @file{.emacs} files:
560 (autoload 'send-pr "send-pr" "Submit a Problem Report." t)
564 Create a mail alias for the Support Site from which you received
565 @code{send-pr}, and for every site with which you wish to use
566 @code{send-pr} to communicate. Each alias must have a suffix of
567 @samp{-gnats}. The Support Site(s) will provide the correct addresses
568 where these aliases should point. For instance, edit your mail aliases
569 file to contain something like:
572 # support sites; for use with send-pr
573 cygnus-gnats: bugs@@cygnus.com # Cygnus Support
574 bumblebee-gnats: bumblebugs@@bumblebee.com # Bumblebee Inc.
575 mycompany-gnats: bugs@@my.company.com (@emph{if you use @sc{gnats} locally})
578 @code{send-pr} automatically searches for these aliases when you type
583 send-pr @var{site}@dots{}
587 @code{send-pr} also uses @var{site} to determine the categories of
588 problems accepted by the site in question by looking in
591 @var{prefix}/lib/gnats/@var{site}
597 @section Setting a default @var{site}
598 @cindex default @var{site}
599 @cindex setting a default @var{site}
601 @code{send-pr} is capable of sending Problem Reports to any number of
602 Support Sites, using mail aliases which have @samp{-gnats} appended them.
603 @code{send-pr} automatically appends the suffix, so that when you type
610 the Problem Report goes to the address noted in the @file{aliases} file
611 as @w{@samp{@var{site}-gnats}}. You can do this in the Emacs version of
612 @code{send-pr} by invoking the program with
619 You are prompted for @var{site}.
621 @var{site} is also used to error-check the @samp{>Category:} field, as a
622 precaution against sending mistaken information (and against sending
623 information to the wrong site).
625 You may also simply type
632 from the shell (or @w{@samp{M-x send-pr}} in Emacs), and the Problem
633 Report you generate will be sent to the @var{site}, which is usually the
634 site from which you received your distribution of @w{@code{send-pr}}.
635 If you use @sc{gnats} at your own organization, the default is usually
636 your local address for reporting problems.
638 To change this, simply edit the file @file{Makefile} before installing
642 GNATS_SITE = @var{site}
646 to reflect the site where you wish to send PRs by default.
648 @c ---------------------------------------------------------------
654 @c ---------------------------------------------------------------