gnu/usr.bin/send-pr/doc/send-pr.texi

   1 @c $FreeBSD: src/gnu/usr.bin/send-pr/doc/send-pr.texi,v 1.2.6.1 2001/03/05 10:44:05 kris Exp $
   2 @c $DragonFly: src/gnu/usr.bin/send-pr/doc/Attic/send-pr.texi,v 1.2 2003/06/17 04:25:48 dillon Exp $
   3
   4 \input texinfo   @c -*-texinfo-*-
   5 @setfilename send-pr.info
   6 @settitle Reporting Problems Using send-pr
   7
   8 @setchapternewpage odd
   9
  10 @include version.texi
  11 @set SENDPR
  12
  13 @ifinfo
  14 @format
  15 START-INFO-DIR-ENTRY
  16 * send-pr: (send-pr).           Reporting problems--using send-pr
  17 END-INFO-DIR-ENTRY
  18 @end format
  19 @end ifinfo
  20
  21 @ifinfo
  22 Copyright @copyright{} 1993, 1994, 1995 Free Software Foundation, Inc.
  23
  24 Permission is granted to make and distribute verbatim copies of
  25 this manual provided the copyright notice and this permission notice
  26 are preserved on all copies.
  27
  28 @ignore
  29 Permission is granted to process this file through TeX and print the
  30 results, provided the printed document carries a copying permission
  31 notice identical to this one except for the removal of this paragraph
  32 (this paragraph not being relevant to the printed manual).
  33
  34 @end ignore
  35
  36 Permission is granted to copy and distribute modified versions of this
  37 manual under the conditions for verbatim copying, provided also that
  38 the entire resulting derived work is distributed under the terms of a
  39 permission notice identical to this one.
  40
  41 Permission is granted to copy and distribute translations of this manual
  42 into another language, under the above conditions for modified versions.
  43 @end ifinfo
  44
  45 @titlepage
  46 @finalout
  47 @title Reporting Problems
  48 @subtitle Using @code{send-pr}, version @value{VERSION}
  49 @subtitle October 1993
  50 @author Jeffrey M. Osier
  51 @author Cygnus Support
  52 @page
  53
  54 @vskip 0pt plus 1filll
  55
  56 Copyright @copyright{} 1993, 1994, 1995 Free Software Foundation, Inc.
  57
  58 Permission is granted to make and distribute verbatim copies of
  59 this manual provided the copyright notice and this permission notice
  60 are preserved on all copies.
  61
  62 Permission is granted to copy and distribute modified versions of this
  63 manual under the conditions for verbatim copying, provided also that
  64 the entire resulting derived work is distributed under the terms of a
  65 permission notice identical to this one.
  66
  67 Permission is granted to copy and distribute translations of this manual
  68 into another language, under the above conditions for modified versions.
  69
  70 @end titlepage
  71
  72 @c ---------------------------------------------------------------
  73 @node Top
  74 @top Overview
  75 @cindex foreword to @code{send-pr}
  76 @cindex overview to @code{send-pr}
  77 @cindex introduction to @code{send-pr}
  78
  79 This manual documents @code{send-pr},
  80 @ifinfo
  81 version @value{VERSION},
  82 @end ifinfo
  83 which uses electronic mail to submit support questions and problem
  84 reports to a central Support Site.  No body of work is perfect, and
  85 support organizations understand this; @code{send-pr} is designed to
  86 allow users who have problems to submit reports of these problems to
  87 sites responsible for supporting the products in question, in a defined
  88 form which can be read by an electronically managed database.
  89
  90 @cindex GNATS
  91 @code{send-pr} is part of a suite of programs known collectively as
  92 @sc{gnats}, the @sc{gnu} Problem Report Management System.  @sc{gnats}
  93 consists of several programs which, used in concert, formulate and
  94 partially administer a database of @dfn{Problem Reports}, or @dfn{PRs},
  95 at a central Support Site.  A PR goes through several states in its
  96 lifetime; @sc{gnats} tracks the PR and all information associated with it
  97 through each state and finally acts as an archive for PRs which have
  98 been @dfn{closed}.
  99
 100 Because @code{send-pr} exists as a shell (@file{/bin/sh}) script and as
 101 an Elisp file for use with @sc{gnu} Emacs, it can be used from any
 102 machine on your network which can run a shell script and/or Emacs.
 103
 104 In general, you can use any editor and mailer to submit valid Problem
 105 Reports, as long as the format required by @sc{gnats} is preserved.
 106 @code{send-pr} automates the process, however, and ensures that certain
 107 fields necessary for automatic processing are present.  @code{send-pr}
 108 is strongly recommended for all initial problem-oriented correspondence
 109 with your Support Site.  The organization you submit Problem Reports to
 110 supplies an address to which further information can be sent; the person
 111 responsible for the category of the problem you report contacts you
 112 directly.
 113
 114 @menu
 115 * send-pr in detail::     Details about send-pr and GNATS
 116 * Invoking send-pr::      Editing and sending PRs
 117 * An Example::            A working example
 118 * Installing send-pr::    Installing send-pr on your system
 119 * Index::
 120 @end menu
 121
 122 @node send-pr in detail
 123 @chapter Details about send-pr and GNATS
 124
 125 @cindex details about @code{send-pr}
 126 @cindex Problem Reports
 127 A @dfn{Problem Report} is a message that describes a problem you are
 128 having with a body of work.  @code{send-pr} organizes this message into
 129 a form which can be understood and automatically processed by @sc{gnats},
 130 the @sc{gnu} Problem Report Management System.  A Problem Report is
 131 organized into @dfn{fields} which contain data describing you, your
 132 organization, and the problem you are announcing (@pxref{Fields,,Problem
 133 Report format}).  Problem Reports go through several defined states in
 134 their lifetimes, from @dfn{open} to @dfn{closed} (@pxref{States,,States
 135 of Problem Reports}).
 136
 137 @menu
 138 * States::                     States of Problem Reports
 139 * Fields::                     Problem Report format
 140 @end menu
 141
 142 @include states.texi
 143
 144 @include fields.texi
 145
 146 @node Invoking send-pr
 147 @chapter Editing and sending PRs
 148 @cindex editing and sending PRs
 149 @cindex sending PRs
 150 @cindex invoking send-pr
 151 @cindex using send-pr
 152 @cindex generating new PRs
 153
 154 @include s-usage.texi
 155
 156 @node An Example
 157 @chapter An Example
 158 @cindex an example
 159 @cindex example PR
 160 @cindex Cygnus Solutions
 161 @cindex @sc{gnu} software support
 162 Cygnus Solutions in Sunnyvale, CA, uses @sc{gnats} and @code{send-pr}
 163 extensively for their support activities.  As a support company, Cygnus
 164 finds problem tracking to be a crucial part of everyday business.
 165 Cygnus supports the @sc{gnu} compiling tools (including @sc{gnats} and
 166 @code{send-pr}) over several many platforms
 167
 168 With each shipment of the Cygnus Solutions Developer's Kit, customers
 169 receive the latest version of @code{send-pr}, which contains an
 170 up-to-date listing of valid categories (values for the @code{>Category:}
 171 field).  Using these tools, Cygnus' customers can communicate their
 172 problems to Cygnus effectively and receive automatic confirmation of
 173 receipt as well as notification of changes in the status of their
 174 reported problems.  Much of Cygnus' support mechanism relies on
 175 electronic mail.
 176
 177 As an example, let's pretend we're a customer of Cygnus Solutions, and
 178 that we're having a problem compiling some of our software using the
 179 @sc{gnu} C compiler, which Cygnus supports.
 180
 181 Assume that we're getting an error in our @code{bifrabulator} program
 182 wherein the @samp{prestidigitation} routines don't match with the
 183 @samp{whatsitsname}.  We've made sure we're following the rules of the
 184 program and checked the Release Notes from Cygnus and found that the bug
 185 isn't already known.  In other words, we're pretty sure we've found a
 186 bug.
 187
 188 @cindex Imaginary Software, Ltd.
 189 Our first step is to call @code{send-pr}.  It really doesn't matter
 190 whether we use @code{send-pr} from the shell or from within Emacs.
 191 Indeed, if we use Emacs as a primary editor, calling @code{send-pr} from
 192 the shell is likely to start @code{send-pr} in an Emacs buffer anyway.
 193 So, since our company, @emph{Imaginary Software, Ltd.}, uses @sc{gnu}
 194 software extensively, we're pretty familiar with Emacs, so from within
 195 Emacs we type
 196 @smallexample
 197 M-x send-pr
 198 @end smallexample
 199 @noindent
 200 and we're greeted with the following screen:
 201
 202 @cindex default PR template
 203 @cindex example of a default template
 204 @cindex blank PR template
 205 @cindex @code{bifrabulator}
 206 @cartouche
 207 @smallexample
 208 SEND-PR: -*- text  -*-
 209 SEND-PR: Lines starting with `SEND-PR' will be removed
 210 SEND-PR: automatically as well as all comments (the text
 211 SEND-PR: below enclosed in `<' and `>').
 212 SEND-PR: Please consult the manual if you are not sure
 213 SEND-PR: how to fill out a problem report.
 214 SEND-PR:
 215 SEND-PR: Choose from the following categories:
 216 SEND-PR:
 217 SEND-PR:           bfd       binutils  bison
 218 SEND-PR: byacc     clib      config    cvs         diff
 219 SEND-PR: doc       emacs     flex      g++         gas
 220 SEND-PR: gcc       gdb       glob      gprof       grep
 221 SEND-PR: info      ispell    kerberos  ld          libg++
 222 SEND-PR: libiberty make      makeinfo  mas         newlib
 223 SEND-PR: other     patch     rcs       readline    send-pr
 224 SEND-PR: test      texindex  texinfo   texinfo.tex
 225 SEND-PR: bifrabulator  <---@emph{note: this one is fake}
 226 SEND-PR:
 227 To: cygnus-bugs@@cygnus.com
 228 Subject:
 229 From: jeffrey@@imaginary.com
 230 Reply-To: jeffrey@@imaginary.com
 231 X-send-pr-version: send-pr @value{VERSION}
 232
 233 >Submitter-Id:  imaginary
 234 >Originator:    Jeffrey Osier
 235 >Organization:
 236 Imaginary Software, Ltd.
 237 >Confidential:  <[ yes | no ] (one line)>
 238 >Synopsis:      <synopsis of the problem (one line)>
 239 >Severity:      <[ non-critical | serious | critical ] (one line)>
 240 >Priority:      <[ low | medium | high ] (one line)>
 241 >Category:      <name of the product (one line)>
 242 >Class:         <[sw-bug|doc-bug|change-request|support](oneline)>
 243 >Release:       <release number or tag (one line)>
 244 >Environment:
 245          <machine, os, target, libraries (multiple lines)>
 246 System: SunOS imaginary.com 4.1.1 1 sun4
 247 Architecture: sun4
 248
 249 >Description:
 250        <precise description of the problem (multiple lines)>
 251 >How-To-Repeat:
 252        <code/input/activities to reproduce (multiple lines)>
 253 >Fix:
 254 @iftex
 255 @hrule
 256 @end iftex
 257 -----Emacs: *send-pr*   (send-pr Fill)----All------------------
 258 @iftex
 259 @hrule
 260 @end iftex
 261 >Category: other[]
 262 @end smallexample
 263 @end cartouche
 264 @page
 265 We know from past experience that we need to set certain information into
 266 each field, so we compile all the information we know about our problem.
 267 We have some sample code which we know should work, even though it
 268 doesn't, so we'll include that.  Below is the completed PR; we send this
 269 using @kbd{C-c C-c}.  (The comments have been truncated).
 270
 271 @cindex completed Problem Report
 272 @cindex example of a completed PR
 273 @cartouche
 274 @smallexample
 275 SEND-PR: Lines starting with `SEND-PR' will be removed
 276 SEND-PR: automatically as well as all comments (the text
 277 SEND-PR: @dots{}
 278 SEND-PR:
 279 To: cygnus-bugs@@cygnus.com
 280 Subject: bifrabulator routines don't match
 281 From: jeffrey@@imaginary.com
 282 Reply-To: jeffrey@@imaginary.com
 283 X-send-pr-version: send-pr @value{VERSION}
 284
 285 >Submitter-Id:  imaginary
 286 >Originator:    Jeffrey Osier
 287 >Organization:
 288 Imaginary Software, Ltd.
 289 >Confidential:  no
 290 >Synopsis:      bifrabulator routines don't match
 291 >Severity:      serious
 292 >Priority:      medium
 293 >Category:      bifrabulator
 294 >Class:         sw-bug
 295 >Release:       progressive-930101
 296 >Environment:
 297 System: SunOS imaginary.com 4.1.1 1 sun4
 298 Architecture: sun4 (SPARC)
 299
 300 >Description:
 301    the following code I fed into the bifrabulator came back
 302    with a strange error.  apparently, the prestidigitation
 303    routine doesn't match with the whatsitsname in all cases.
 304
 305 >How-To-Repeat:
 306    call the bifrabulator on the following code.
 307    @emph{code sample@dots{}}
 308
 309 >Fix:
 310 @iftex
 311 @hrule
 312 @end iftex
 313 -----Emacs: *send-pr*   (send-pr Fill)----All------------------
 314 @iftex
 315 @hrule
 316 @end iftex
 317 To send the problem report use: C-c C-c
 318 @end smallexample
 319 @end cartouche
 320
 321 We type @kbd{C-c C-c}, and off it goes.  Now, we depend on Cygnus
 322 Support to figure out the answer to our problem.
 323
 324 Soon afterward, we get the following message from Cygnus:
 325
 326 @smallexample
 327 @group
 328 From: gnats (GNATS management)
 329 Sender: gnats-admin
 330 Reply-To: hacker@@cygnus.com
 331 To: jeffrey@@imaginary.com
 332 Subject: Re: bifrabulator/1425: routines don't match
 333
 334 Thank you very much for your problem report.
 335 It has the internal identification: g++/1425.
 336 The individual assigned to look at your bug is:  hacker
 337 (F.B. Hacker)
 338
 339 Category: bifrabulator
 340 Responsible: hacker
 341 Synopsis: bifrabulator routines don't match
 342 Arrival-Date: Sat Feb 30 03:12:55 1993
 343 @end group
 344 @end smallexample
 345
 346 @noindent
 347 This is our receipt that the bug has been accepted and forwarded to the
 348 responsible party.
 349
 350 @noindent
 351 A while later, we get the analysis:
 352
 353 @smallexample
 354 @group
 355 To:  jeffrey@@imaginary.com
 356 From:  hacker@@cygnus.com
 357 Subject:  Re: bifrabulator/1425: routines don't match
 358 Reply-To: hacker@@cygnus.com
 359
 360 Got your message, Jeff.  It seems that the bifrabulator was
 361 confusing the prestidigitation routines with the realitychecker
 362 when lexically parsing the whatsitsname.
 363
 364 I'm working on robustisizing the bifrabulator now.
 365
 366 How about lunch next week?
 367 --
 368 F.B. Hacker
 369 Cygnus Solutions, Sunnyvale, CA  408 542 9600
 370 #include <std-disclaimer.h>
 371 @end group
 372 @end smallexample
 373
 374 @noindent
 375 About the same time, we get another message from Cygnus.
 376
 377 @cindex state change example
 378 @cindex example of a state change
 379 @smallexample
 380 @group
 381 From: hacker@@cygnus.com
 382 To:  jeffrey@@imaginary.com
 383 Subject:  Re: bifrabulator/1425: doesn't match prestidig
 384 Reply-To:  hacker@@cygnus.com
 385
 386
 387              `F.B. Hacker' changed the state to `analyzed'.
 388
 389 State-Changed-From-To: open-analyzed
 390 State-Changed-By: hacker
 391 State-Changed-When: Fri Feb 31 1993 08:59:16 1993
 392 State-Changed-Why:
 393     figured out the problem, working on a patch this afternoon
 394 --
 395 F.B. Hacker
 396 Cygnus Solutions, Sunnyvale, CA  408 542 9600
 397 #include <std-disclaimer.h>
 398 @end group
 399 @end smallexample
 400
 401 @noindent
 402 The bug has now been analyzed, and Cygnus is working on a solution.
 403
 404 @noindent
 405 Sometime later, we get more mail from F.B.:
 406
 407 @smallexample
 408 @group
 409 To:  jeffrey@@imaginary.com
 410 From:  hacker@@cygnus.com
 411 Subject:  Re: bifrabulator/1425: routines don't match
 412 Reply-To: hacker@@cygnus.com
 413
 414 There's a patch now that you can ftp over and check out.
 415
 416 Hey, that joke you sent me was great!  The one about the
 417 strings walking into a bar...  my boss laughed for an hour!
 418 --
 419 F.B. Hacker
 420 Cygnus Solutions, Sunnyvale, CA  408 542 9600
 421 #include <std-disclaimer.h>
 422 @end group
 423 @end smallexample
 424 @sp 2
 425 @smallexample
 426 @group
 427 From: hacker@@cygnus.com
 428 To:  jeffrey@@imaginary.com
 429 Subject:  Re: bifrabulator/1425: doesn't match prestidig
 430 Reply-To:  hacker@@cygnus.com
 431
 432
 433              `F.B. Hacker' changed the state to `feedback'.
 434
 435 State-Changed-From-To: analyzed-feedback
 436 State-Changed-By: hacker
 437 State-Changed-When: Fri Feb 31 1993 23:43:16 1993
 438 State-Changed-Why:
 439     got the patch finished, notified Jeff at Imaginary Software
 440 --
 441 F.B. Hacker
 442 Cygnus Solutions, Sunnyvale, CA  408 542 9600
 443 #include <std-disclaimer.h>
 444 @end group
 445 @end smallexample
 446
 447 @noindent
 448 The bug has gone into @dfn{feedback} status now, until we get the patch,
 449 install it and test it.  When everything tests well, we can mail F.B.
 450 back and tell him the bug's been fixed, and he can change the state of
 451 the PR from @dfn{feedback} to @dfn{closed}.
 452
 453 Following is a list of valid @samp{>Category:} entries that are
 454 supported by Cygnus.
 455
 456 @menu
 457 * Valid Categories::
 458 @end menu
 459
 460 @c FIXME - is this list up to date?
 461 @include categ.texi
 462
 463 @node Installing send-pr
 464 @appendix Installing @code{send-pr} on your system
 465 @cindex installation
 466
 467 If you receive @code{send-pr} as part of a larger software distribution,
 468 it probably gets installed when the full distribution is installed.  If
 469 you are using @sc{gnats} at your site as well, you must decide where
 470 @code{send-pr} sends Problem Reports by default; see @ref{default site,,
 471 Setting a default @var{site}}.
 472
 473 @menu
 474 * installation::   installing `send-pr' by itself
 475 * default site::   setting a default site
 476 @end menu
 477
 478 @node installation
 479 @section Installing @code{send-pr} by itself
 480 @cindex installation procedure
 481
 482 Install @code{send-pr} by following these steps (you may need
 483 @code{root} access in order to change the @file{aliases} file and to
 484 install @code{send-pr}):
 485
 486 @itemize @bullet
 487 @item
 488 Unpack the distribution into a directory which we refer to as
 489 @var{srcdir}.
 490
 491 @item
 492 Edit the file @file{Makefile} to reflect local conventions.
 493 Specifically, you should edit the variable @samp{prefix} to alter the
 494 installation location.  The default is @file{/usr/local}.  All files are
 495 installed under @samp{prefix} (see below).
 496
 497 @item @emph{Run}
 498 @smallexample
 499 make all install [ info ] [ install-info ] [ clean ]
 500 @end smallexample
 501
 502 @noindent
 503 The targets mean the following:
 504
 505 @table @code
 506 @item all
 507 Builds @code{send-pr} and @code{install-sid}
 508
 509 @item install
 510 Installs the following:
 511
 512 @table @code
 513 @item install-sid
 514 @itemx send-pr
 515 into @file{@var{prefix}/bin}
 516
 517 @item send-pr.1
 518 into @file{@var{prefix}/man/man1}
 519
 520 @item @var{site}
 521 the list of valid @var{categories} for the Support Site from which you
 522 received @code{send-pr}, installed as
 523 @w{@file{@var{prefix}/share/gnats/@var{site}}}
 524
 525 @item send-pr.el
 526 into @w{@file{@var{prefix}/share/emacs/lisp}}@footnote{If your main Emacs
 527 lisp repository is in a different directory from this, substitute that
 528 directory for @w{@file{@var{prefix}/share/emacs/lisp}}.}
 529 @end table
 530
 531 @item info (@emph{optional})
 532 Builds @file{send-pr.info} from @file{send-pr.texi}@*
 533 @c FIXME - is this still true?
 534 (@file{send-pr.info} is included with this distribution)
 535
 536 @item install-info (@emph{optional})
 537 Installs @file{send-pr.info} into @w{@file{@var{prefix}/info}}
 538
 539 @item clean (@emph{optional})
 540 Removes all intermediary build files that can be rebuilt from source
 541 code
 542 @end table
 543
 544 @item
 545 Run
 546
 547 @smallexample
 548 install-sid @var{your-sid}
 549 @end smallexample
 550
 551 @noindent
 552 where @var{your-sid} is the identification code you received with
 553 @w{@code{send-pr}}.  @code{send-pr} automatically inserts this value
 554 into the template field @samp{>Submitter-Id:}.  If you've downloaded
 555 @code{send-pr} from the Net, use @samp{net} for this value.
 556
 557 @item
 558 Place the following line in
 559 @w{@file{@var{prefix}/share/emacs/lisp/default.el}}, or instruct your
 560 users to place the following line in their @file{.emacs} files:
 561
 562 @smallexample
 563 (autoload 'send-pr "send-pr" "Submit a Problem Report." t)
 564 @end smallexample
 565
 566 @item
 567 Create a mail alias for the Support Site from which you received
 568 @code{send-pr}, and for every site with which you wish to use
 569 @code{send-pr} to communicate.  Each alias must have a suffix of
 570 @samp{-gnats}.  The Support Site(s) will provide the correct addresses
 571 where these aliases should point.  For instance, edit your mail aliases
 572 file to contain something like:
 573
 574 @smallexample
 575 # support sites; for use with send-pr
 576 cygnus-gnats:     bugs@@cygnus.com            # Cygnus Solutions
 577 bumblebee-gnats:  bumblebugs@@bumblebee.com   # Bumblebee Inc.
 578 mycompany-gnats:  bugs@@my.company.com (@emph{if you use @sc{gnats} locally})
 579 @end smallexample
 580
 581 @code{send-pr} automatically searches for these aliases when you type
 582
 583 @smallexample
 584 send-pr cygnus
 585 send-pr bumblebee
 586 send-pr @var{site}@dots{}
 587 @end smallexample
 588
 589 @noindent
 590 @code{send-pr} also uses @var{site} to determine the categories of
 591 problems accepted by the site in question by looking in
 592
 593 @smallexample
 594 @var{prefix}/share/gnats/@var{site}
 595 @end smallexample
 596
 597 @end itemize
 598
 599 @node default site
 600 @section Setting a default @var{site}
 601 @cindex default @var{site}
 602 @cindex setting a default @var{site}
 603
 604 @code{send-pr} is capable of sending Problem Reports to any number of
 605 Support Sites, using mail aliases which have @samp{-gnats} appended them.
 606 @code{send-pr} automatically appends the suffix, so that when you type
 607
 608 @smallexample
 609 send-pr @var{site}
 610 @end smallexample
 611
 612 @noindent
 613 the Problem Report goes to the address noted in the @file{aliases} file
 614 as @w{@samp{@var{site}-gnats}}.  You can do this in the Emacs version of
 615 @code{send-pr} by invoking the program with
 616
 617 @smallexample
 618 C-u M-x send-pr
 619 @end smallexample
 620
 621 @noindent
 622 You are prompted for @var{site}.
 623
 624 @var{site} is also used to error-check the @samp{>Category:} field, as a
 625 precaution against sending mistaken information (and against sending
 626 information to the wrong site).
 627
 628 You may also simply type
 629
 630 @smallexample
 631 send-pr
 632 @end smallexample
 633
 634 @noindent
 635 from the shell (or @w{@samp{M-x send-pr}} in Emacs), and the Problem
 636 Report you generate will be sent to the @var{site}, which is usually the
 637 site from which you received your distribution of @w{@code{send-pr}}.
 638 If you use @sc{gnats} at your own organization, the default is usually
 639 your local address for reporting problems.
 640
 641 To change this, simply edit the file @file{Makefile} before installing
 642 and change the line
 643
 644 @smallexample
 645 GNATS_SITE = @var{site}
 646 @end smallexample
 647
 648 @noindent
 649 to reflect the site where you wish to send PRs by default.
 650
 651 @c ---------------------------------------------------------------
 652 @node Index
 653 @unnumbered Index
 654
 655 @printindex cp
 656
 657 @c ---------------------------------------------------------------
 658 @contents
 659 @bye