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

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