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

   1 @c $FreeBSD$
   2
   3 \input texinfo   @c -*-texinfo-*-
   4 @setfilename send-pr.info
   5 @settitle Reporting Problems Using send-pr
   6
   7 @setchapternewpage odd
   8
   9 @include version.texi
  10 @set SENDPR
  11
  12 @ifinfo
  13 @format
  14 START-INFO-DIR-ENTRY
  15 * send-pr: (send-pr).           Reporting problems--using send-pr
  16 END-INFO-DIR-ENTRY
  17 @end format
  18 @end ifinfo
  19
  20 @ifinfo
  21 Copyright @copyright{} 1993, 1994, 1995 Free Software Foundation, Inc.
  22
  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.
  26
  27 @ignore
  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).
  32
  33 @end ignore
  34
  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.
  39
  40 Permission is granted to copy and distribute translations of this manual
  41 into another language, under the above conditions for modified versions.
  42 @end ifinfo
  43
  44 @titlepage
  45 @finalout
  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
  51 @page
  52
  53 @vskip 0pt plus 1filll
  54
  55 Copyright @copyright{} 1993, 1994, 1995 Free Software Foundation, Inc.
  56
  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.
  60
  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.
  65
  66 Permission is granted to copy and distribute translations of this manual
  67 into another language, under the above conditions for modified versions.
  68
  69 @end titlepage
  70
  71 @c ---------------------------------------------------------------
  72 @node Top
  73 @top Overview
  74 @cindex foreword to @code{send-pr}
  75 @cindex overview to @code{send-pr}
  76 @cindex introduction to @code{send-pr}
  77
  78 This manual documents @code{send-pr},
  79 @ifinfo
  80 version @value{VERSION},
  81 @end ifinfo
  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.
  88
  89 @cindex GNATS
  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
  97 been @dfn{closed}.
  98
  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.
 102
 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
 111 directly.
 112
 113 @menu
 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
 118 * Index::
 119 @end menu
 120
 121 @node send-pr in detail
 122 @chapter Details about send-pr and GNATS
 123
 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}).
 135
 136 @menu
 137 * States::                     States of Problem Reports
 138 * Fields::                     Problem Report format
 139 @end menu
 140
 141 @include states.texi
 142
 143 @include fields.texi
 144
 145 @node Invoking send-pr
 146 @chapter Editing and sending PRs
 147 @cindex editing and sending PRs
 148 @cindex sending PRs
 149 @cindex invoking send-pr
 150 @cindex using send-pr
 151 @cindex generating new PRs
 152
 153 @include s-usage.texi
 154
 155 @node An Example
 156 @chapter An Example
 157 @cindex an example
 158 @cindex example PR
 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
 166
 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
 174 electronic mail.
 175
 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.
 179
 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
 185 bug.
 186
 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
 194 Emacs we type
 195 @smallexample
 196 M-x send-pr
 197 @end smallexample
 198 @noindent
 199 and we're greeted with the following screen:
 200
 201 @cindex default PR template
 202 @cindex example of a default template
 203 @cindex blank PR template
 204 @cindex @code{bifrabulator}
 205 @cartouche
 206 @smallexample
 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.
 213 SEND-PR:
 214 SEND-PR: Choose from the following categories:
 215 SEND-PR:
 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}
 225 SEND-PR:
 226 To: cygnus-bugs@@cygnus.com
 227 Subject:
 228 From: jeffrey@@imaginary.com
 229 Reply-To: jeffrey@@imaginary.com
 230 X-send-pr-version: send-pr @value{VERSION}
 231
 232 >Submitter-Id:  imaginary
 233 >Originator:    Jeffrey Osier
 234 >Organization:
 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)>
 243 >Environment:
 244          <machine, os, target, libraries (multiple lines)>
 245 System: SunOS imaginary.com 4.1.1 1 sun4
 246 Architecture: sun4
 247
 248 >Description:
 249        <precise description of the problem (multiple lines)>
 250 >How-To-Repeat:
 251        <code/input/activities to reproduce (multiple lines)>
 252 >Fix:
 253 @iftex
 254 @hrule
 255 @end iftex
 256 -----Emacs: *send-pr*   (send-pr Fill)----All------------------
 257 @iftex
 258 @hrule
 259 @end iftex
 260 >Category: other[]
 261 @end smallexample
 262 @end cartouche
 263 @page
 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).
 269
 270 @cindex completed Problem Report
 271 @cindex example of a completed PR
 272 @cartouche
 273 @smallexample
 274 SEND-PR: Lines starting with `SEND-PR' will be removed
 275 SEND-PR: automatically as well as all comments (the text
 276 SEND-PR: @dots{}
 277 SEND-PR:
 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}
 283
 284 >Submitter-Id:  imaginary
 285 >Originator:    Jeffrey Osier
 286 >Organization:
 287 Imaginary Software, Ltd.
 288 >Confidential:  no
 289 >Synopsis:      bifrabulator routines don't match
 290 >Severity:      serious
 291 >Priority:      medium
 292 >Category:      bifrabulator
 293 >Class:         sw-bug
 294 >Release:       progressive-930101
 295 >Environment:
 296 System: SunOS imaginary.com 4.1.1 1 sun4
 297 Architecture: sun4 (SPARC)
 298
 299 >Description:
 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.
 303
 304 >How-To-Repeat:
 305    call the bifrabulator on the following code.
 306    @emph{code sample@dots{}}
 307
 308 >Fix:
 309 @iftex
 310 @hrule
 311 @end iftex
 312 -----Emacs: *send-pr*   (send-pr Fill)----All------------------
 313 @iftex
 314 @hrule
 315 @end iftex
 316 To send the problem report use: C-c C-c
 317 @end smallexample
 318 @end cartouche
 319
 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.
 322
 323 Soon afterward, we get the following message from Cygnus:
 324
 325 @smallexample
 326 @group
 327 From: gnats (GNATS management)
 328 Sender: gnats-admin
 329 Reply-To: hacker@@cygnus.com
 330 To: jeffrey@@imaginary.com
 331 Subject: Re: bifrabulator/1425: routines don't match
 332
 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
 336 (F.B. Hacker)
 337
 338 Category: bifrabulator
 339 Responsible: hacker
 340 Synopsis: bifrabulator routines don't match
 341 Arrival-Date: Sat Feb 30 03:12:55 1993
 342 @end group
 343 @end smallexample
 344
 345 @noindent
 346 This is our receipt that the bug has been accepted and forwarded to the
 347 responsible party.
 348
 349 @noindent
 350 A while later, we get the analysis:
 351
 352 @smallexample
 353 @group
 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
 358
 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.
 362
 363 I'm working on robustisizing the bifrabulator now.
 364
 365 How about lunch next week?
 366 --
 367 F.B. Hacker
 368 Cygnus Solutions, Sunnyvale, CA  408 542 9600
 369 #include <std-disclaimer.h>
 370 @end group
 371 @end smallexample
 372
 373 @noindent
 374 About the same time, we get another message from Cygnus.
 375
 376 @cindex state change example
 377 @cindex example of a state change
 378 @smallexample
 379 @group
 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
 384
 385
 386              `F.B. Hacker' changed the state to `analyzed'.
 387
 388 State-Changed-From-To: open-analyzed
 389 State-Changed-By: hacker
 390 State-Changed-When: Fri Feb 31 1993 08:59:16 1993
 391 State-Changed-Why:
 392     figured out the problem, working on a patch this afternoon
 393 --
 394 F.B. Hacker
 395 Cygnus Solutions, Sunnyvale, CA  408 542 9600
 396 #include <std-disclaimer.h>
 397 @end group
 398 @end smallexample
 399
 400 @noindent
 401 The bug has now been analyzed, and Cygnus is working on a solution.
 402
 403 @noindent
 404 Sometime later, we get more mail from F.B.:
 405
 406 @smallexample
 407 @group
 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
 412
 413 There's a patch now that you can ftp over and check out.
 414
 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!
 417 --
 418 F.B. Hacker
 419 Cygnus Solutions, Sunnyvale, CA  408 542 9600
 420 #include <std-disclaimer.h>
 421 @end group
 422 @end smallexample
 423 @sp 2
 424 @smallexample
 425 @group
 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
 430
 431
 432              `F.B. Hacker' changed the state to `feedback'.
 433
 434 State-Changed-From-To: analyzed-feedback
 435 State-Changed-By: hacker
 436 State-Changed-When: Fri Feb 31 1993 23:43:16 1993
 437 State-Changed-Why:
 438     got the patch finished, notified Jeff at Imaginary Software
 439 --
 440 F.B. Hacker
 441 Cygnus Solutions, Sunnyvale, CA  408 542 9600
 442 #include <std-disclaimer.h>
 443 @end group
 444 @end smallexample
 445
 446 @noindent
 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}.
 451
 452 Following is a list of valid @samp{>Category:} entries that are
 453 supported by Cygnus.
 454
 455 @menu
 456 * Valid Categories::
 457 @end menu
 458
 459 @c FIXME - is this list up to date?
 460 @include categ.texi
 461
 462 @node Installing send-pr
 463 @appendix Installing @code{send-pr} on your system
 464 @cindex installation
 465
 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}}.
 471
 472 @menu
 473 * installation::   installing `send-pr' by itself
 474 * default site::   setting a default site
 475 @end menu
 476
 477 @node installation
 478 @section Installing @code{send-pr} by itself
 479 @cindex installation procedure
 480
 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}):
 484
 485 @itemize @bullet
 486 @item
 487 Unpack the distribution into a directory which we refer to as
 488 @var{srcdir}.
 489
 490 @item
 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).
 495
 496 @item @emph{Run}
 497 @smallexample
 498 make all install [ info ] [ install-info ] [ clean ]
 499 @end smallexample
 500
 501 @noindent
 502 The targets mean the following:
 503
 504 @table @code
 505 @item all
 506 Builds @code{send-pr} and @code{install-sid}
 507
 508 @item install
 509 Installs the following:
 510
 511 @table @code
 512 @item install-sid
 513 @itemx send-pr
 514 into @file{@var{prefix}/bin}
 515
 516 @item send-pr.1
 517 into @file{@var{prefix}/man/man1}
 518
 519 @item @var{site}
 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}}}
 523
 524 @item send-pr.el
 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}}.}
 528 @end table
 529
 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)
 534
 535 @item install-info (@emph{optional})
 536 Installs @file{send-pr.info} into @w{@file{@var{prefix}/info}}
 537
 538 @item clean (@emph{optional})
 539 Removes all intermediary build files that can be rebuilt from source
 540 code
 541 @end table
 542
 543 @item
 544 Run
 545
 546 @smallexample
 547 install-sid @var{your-sid}
 548 @end smallexample
 549
 550 @noindent
 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.
 555
 556 @item
 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:
 560
 561 @smallexample
 562 (autoload 'send-pr "send-pr" "Submit a Problem Report." t)
 563 @end smallexample
 564
 565 @item
 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:
 572
 573 @smallexample
 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})
 578 @end smallexample
 579
 580 @code{send-pr} automatically searches for these aliases when you type
 581
 582 @smallexample
 583 send-pr cygnus
 584 send-pr bumblebee
 585 send-pr @var{site}@dots{}
 586 @end smallexample
 587
 588 @noindent
 589 @code{send-pr} also uses @var{site} to determine the categories of
 590 problems accepted by the site in question by looking in
 591
 592 @smallexample
 593 @var{prefix}/share/gnats/@var{site}
 594 @end smallexample
 595
 596 @end itemize
 597
 598 @node default site
 599 @section Setting a default @var{site}
 600 @cindex default @var{site}
 601 @cindex setting a default @var{site}
 602
 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
 606
 607 @smallexample
 608 send-pr @var{site}
 609 @end smallexample
 610
 611 @noindent
 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
 615
 616 @smallexample
 617 C-u M-x send-pr
 618 @end smallexample
 619
 620 @noindent
 621 You are prompted for @var{site}.
 622
 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).
 626
 627 You may also simply type
 628
 629 @smallexample
 630 send-pr
 631 @end smallexample
 632
 633 @noindent
 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.
 639
 640 To change this, simply edit the file @file{Makefile} before installing
 641 and change the line
 642
 643 @smallexample
 644 GNATS_SITE = @var{site}
 645 @end smallexample
 646
 647 @noindent
 648 to reflect the site where you wish to send PRs by default.
 649
 650 @c ---------------------------------------------------------------
 651 @node Index
 652 @unnumbered Index
 653
 654 @printindex cp
 655
 656 @c ---------------------------------------------------------------
 657 @contents
 658 @bye