Source

gnats / texi / send-pr.texi

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
\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 Support
@cindex @sc{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
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.