send-pr.texi revision 5476
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 12START-INFO-DIR-ENTRY 13* send-pr:: Reporting problems--using send-pr 14END-INFO-DIR-ENTRY 15@end format 16@end ifinfo 17 18@ifinfo 19Copyright @copyright{} 1993 Free Software Foundation, Inc. 20 21Permission is granted to make and distribute verbatim copies of 22this manual provided the copyright notice and this permission notice 23are preserved on all copies. 24 25@ignore 26Permission is granted to process this file through TeX and print the 27results, provided the printed document carries a copying permission 28notice 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 33Permission is granted to copy and distribute modified versions of this 34manual under the conditions for verbatim copying, provided also that 35the entire resulting derived work is distributed under the terms of a 36permission notice identical to this one. 37 38Permission is granted to copy and distribute translations of this manual 39into 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 53Copyright @copyright{} 1993 Free Software Foundation, Inc. 54 55Permission is granted to make and distribute verbatim copies of 56this manual provided the copyright notice and this permission notice 57are preserved on all copies. 58 59Permission is granted to copy and distribute modified versions of this 60manual under the conditions for verbatim copying, provided also that 61the entire resulting derived work is distributed under the terms of a 62permission notice identical to this one. 63 64Permission is granted to copy and distribute translations of this manual 65into 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 76This manual documents @code{send-pr}, 77@ifinfo 78version @value{VERSION}, 79@end ifinfo 80which uses electronic mail to submit support questions and problem 81reports to a central Support Site. No body of work is perfect, and 82support organizations understand this; @code{send-pr} is designed to 83allow users who have problems to submit reports of these problems to 84sites responsible for supporting the products in question, in a defined 85form 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} 90consists of several programs which, used in concert, formulate and 91partially administer a database of @dfn{Problem Reports}, or @dfn{PRs}, 92at a central Support Site. A PR goes through several states in its 93lifetime; @sc{gnats} tracks the PR and all information associated with it 94through each state and finally acts as an archive for PRs which have 95been @dfn{closed}. 96 97Because @code{send-pr} exists as a shell (@file{/bin/sh}) script and as 98an Elisp file for use with @sc{gnu} Emacs, it can be used from any 99machine on your network which can run a shell script and/or Emacs. 100 101In general, you can use any editor and mailer to submit valid Problem 102Reports, as long as the format required by @sc{gnats} is preserved. 103@code{send-pr} automates the process, however, and ensures that certain 104fields necessary for automatic processing are present. @code{send-pr} 105is strongly recommended for all initial problem-oriented correspondence 106with your Support Site. The organization you submit Problem Reports to 107supplies an address to which further information can be sent; the person 108responsible for the category of the problem you report contacts you 109directly. 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 124A @dfn{Problem Report} is a message that describes a problem you are 125having with a body of work. @code{send-pr} organizes this message into 126a form which can be understood and automatically processed by @sc{gnats}, 127the @sc{gnu} Problem Report Management System. A Problem Report is 128organized into @dfn{fields} which contain data describing you, your 129organization, and the problem you are announcing (@pxref{Fields,,Problem 130Report format}). Problem Reports go through several defined states in 131their lifetimes, from @dfn{open} to @dfn{closed} (@pxref{States,,States 132of 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 160Cygnus Support in Mountain View, CA, uses @sc{gnats} and @code{send-pr} 161extensively for their support activities. As a support company, Cygnus 162finds problem tracking to be a crucial part of everyday business. 163Cygnus supports the @sc{gnu} compiling tools (including @sc{gnats} and 164@code{send-pr}) over several many platforms 165 166With each shipment of the Cygnus Support Developer's Kit, customers 167receive the latest version of @code{send-pr}, which contains an 168up-to-date listing of valid categories (values for the @code{>Category:} 169field). Using these tools, Cygnus' customers can communicate their 170problems to Cygnus effectively and receive automatic confirmation of 171receipt as well as notification of changes in the status of their 172reported problems. Much of Cygnus' support mechanism relies on 173electronic mail. 174 175As an example, let's pretend we're a customer of Cygnus Support, and 176that we're having a problem compiling some of our software using the 177@sc{gnu} C compiler, which Cygnus supports. 178 179Assume that we're getting an error in our @code{bifrabulator} program 180wherein the @samp{prestidigitation} routines don't match with the 181@samp{whatsitsname}. We've made sure we're following the rules of the 182program and checked the Release Notes from Cygnus and found that the bug 183isn't already known. In other words, we're pretty sure we've found a 184bug. 185 186@cindex Imaginary Software, Ltd. 187Our first step is to call @code{send-pr}. It really doesn't matter 188whether we use @code{send-pr} from the shell or from within Emacs. 189Indeed, if we use Emacs as a primary editor, calling @code{send-pr} from 190the shell is likely to start @code{send-pr} in an Emacs buffer anyway. 191So, since our company, @emph{Imaginary Software, Ltd.}, uses @sc{gnu} 192software extensively, we're pretty familiar with Emacs, so from within 193Emacs we type 194@smallexample 195M-x send-pr 196@end smallexample 197@noindent 198and 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 206SEND-PR: -*- text -*- 207SEND-PR: Lines starting with `SEND-PR' will be removed 208SEND-PR: automatically as well as all comments (the text 209SEND-PR: below enclosed in `<' and `>'). 210SEND-PR: Please consult the manual if you are not sure 211SEND-PR: how to fill out a problem report. 212SEND-PR: 213SEND-PR: Choose from the following categories: 214SEND-PR: 215SEND-PR: bfd binutils bison 216SEND-PR: byacc clib config cvs diff 217SEND-PR: doc emacs flex g++ gas 218SEND-PR: gcc gdb glob gprof grep 219SEND-PR: info ispell kerberos ld libg++ 220SEND-PR: libiberty make makeinfo mas newlib 221SEND-PR: other patch rcs readline send-pr 222SEND-PR: test texindex texinfo texinfo.tex 223SEND-PR: bifrabulator <---@emph{note: this one is fake} 224SEND-PR: 225To: cygnus-bugs@@cygnus.com 226Subject: 227From: jeffrey@@imaginary.com 228Reply-To: jeffrey@@imaginary.com 229X-send-pr-version: send-pr @value{VERSION} 230 231>Submitter-Id: imaginary 232>Originator: Jeffrey Osier 233>Organization: 234Imaginary 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)> 244System: SunOS imaginary.com 4.1.1 1 sun4 245Architecture: 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 263We know from past experience that we need to set certain information into 264each field, so we compile all the information we know about our problem. 265We have some sample code which we know should work, even though it 266doesn't, so we'll include that. Below is the completed PR; we send this 267using @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 273SEND-PR: Lines starting with `SEND-PR' will be removed 274SEND-PR: automatically as well as all comments (the text 275SEND-PR: @dots{} 276SEND-PR: 277To: cygnus-bugs@@cygnus.com 278Subject: bifrabulator routines don't match 279From: jeffrey@@imaginary.com 280Reply-To: jeffrey@@imaginary.com 281X-send-pr-version: send-pr @value{VERSION} 282 283>Submitter-Id: imaginary 284>Originator: Jeffrey Osier 285>Organization: 286Imaginary 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: 295System: SunOS imaginary.com 4.1.1 1 sun4 296Architecture: 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 315To send the problem report use: C-c C-c 316@end smallexample 317@end cartouche 318 319We type @kbd{C-c C-c}, and off it goes. Now, we depend on Cygnus 320Support to figure out the answer to our problem. 321 322Soon afterward, we get the following message from Cygnus: 323 324@smallexample 325@group 326From: gnats (GNATS management) 327Sender: gnats-admin 328Reply-To: hacker@@cygnus.com 329To: jeffrey@@imaginary.com 330Subject: Re: bifrabulator/1425: routines don't match 331 332Thank you very much for your problem report. 333It has the internal identification: g++/1425. 334The individual assigned to look at your bug is: hacker 335(F.B. Hacker) 336 337Category: bifrabulator 338Responsible: hacker 339Synopsis: bifrabulator routines don't match 340Arrival-Date: Sat Feb 30 03:12:55 1993 341@end group 342@end smallexample 343 344@noindent 345This is our receipt that the bug has been accepted and forwarded to the 346responsible party. 347 348@noindent 349A while later, we get the analysis: 350 351@smallexample 352@group 353To: jeffrey@@imaginary.com 354From: hacker@@cygnus.com 355Subject: Re: bifrabulator/1425: routines don't match 356Reply-To: hacker@@cygnus.com 357 358Got your message, Jeff. It seems that the bifrabulator was 359confusing the prestidigitation routines with the realitychecker 360when lexically parsing the whatsitsname. 361 362I'm working on robustisizing the bifrabulator now. 363 364How about lunch next week? 365-- 366F.B. Hacker 367Cygnus Support, Mountain View, CA 415 903 1400 368#include <std-disclaimer.h> 369@end group 370@end smallexample 371 372@noindent 373About 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 379From: hacker@@cygnus.com 380To: jeffrey@@imaginary.com 381Subject: Re: bifrabulator/1425: doesn't match prestidig 382Reply-To: hacker@@cygnus.com 383 384 385 `F.B. Hacker' changed the state to `analyzed'. 386 387State-Changed-From-To: open-analyzed 388State-Changed-By: hacker 389State-Changed-When: Fri Feb 31 1993 08:59:16 1993 390State-Changed-Why: 391 figured out the problem, working on a patch this afternoon 392-- 393F.B. Hacker 394Cygnus Support, Mountain View, CA 415 903 1400 395#include <std-disclaimer.h> 396@end group 397@end smallexample 398 399@noindent 400The bug has now been analyzed, and Cygnus is working on a solution. 401 402@noindent 403Sometime later, we get more mail from F.B.: 404 405@smallexample 406@group 407To: jeffrey@@imaginary.com 408From: hacker@@cygnus.com 409Subject: Re: bifrabulator/1425: routines don't match 410Reply-To: hacker@@cygnus.com 411 412There's a patch now that you can ftp over and check out. 413 414Hey, that joke you sent me was great! The one about the 415strings walking into a bar... my boss laughed for an hour! 416-- 417F.B. Hacker 418Cygnus 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 425From: hacker@@cygnus.com 426To: jeffrey@@imaginary.com 427Subject: Re: bifrabulator/1425: doesn't match prestidig 428Reply-To: hacker@@cygnus.com 429 430 431 `F.B. Hacker' changed the state to `feedback'. 432 433State-Changed-From-To: analyzed-feedback 434State-Changed-By: hacker 435State-Changed-When: Fri Feb 31 1993 23:43:16 1993 436State-Changed-Why: 437 got the patch finished, notified Jeff at Imaginary Software 438-- 439F.B. Hacker 440Cygnus Support, Mountain View, CA 415 903 1400 441#include <std-disclaimer.h> 442@end group 443@end smallexample 444 445@noindent 446The bug has gone into @dfn{feedback} status now, until we get the patch, 447install it and test it. When everything tests well, we can mail F.B. 448back and tell him the bug's been fixed, and he can change the state of 449the PR from @dfn{feedback} to @dfn{closed}. 450 451Following is a list of valid @samp{>Category:} entries that are 452supported 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 465If you receive @code{send-pr} as part of a larger software distribution, 466it probably gets installed when the full distribution is installed. If 467you 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,, 469Setting 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 480Install @code{send-pr} by following these steps (you may need 481@code{root} access in order to change the @file{aliases} file and to 482install @code{send-pr}): 483 484@itemize @bullet 485@item 486Unpack the distribution into a directory which we refer to as 487@var{srcdir}. 488 489@item 490Edit the file @file{Makefile} to reflect local conventions. 491Specifically, you should edit the variable @samp{prefix} to alter the 492installation location. The default is @file{/usr/local}. All files are 493installed under @samp{prefix} (see below). 494 495@item @emph{Run} 496@smallexample 497make all install [ info ] [ install-info ] [ clean ] 498@end smallexample 499 500@noindent 501The targets mean the following: 502 503@table @code 504@item all 505Builds @code{send-pr} and @code{install-sid} 506 507@item install 508Installs the following: 509 510@table @code 511@item install-sid 512@itemx send-pr 513into @file{@var{prefix}/bin} 514 515@item send-pr.1 516into @file{@var{prefix}/man/man1} 517 518@item @var{site} 519the list of valid @var{categories} for the Support Site from which you 520received @code{send-pr}, installed as 521@w{@file{@var{prefix}/lib/gnats/@var{site}}} 522 523@item send-pr.el 524into @w{@file{@var{prefix}/lib/emacs/lisp}}@footnote{If your main Emacs 525lisp repository is in a different directory from this, substitute that 526directory for @w{@file{@var{prefix}/lib/emacs/lisp}}.} 527@end table 528 529@item info (@emph{optional}) 530Builds @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}) 535Installs @file{send-pr.info} into @w{@file{@var{prefix}/info}} 536 537@item clean (@emph{optional}) 538Removes all intermediary build files that can be rebuilt from source 539code 540@end table 541 542@item 543Run 544 545@smallexample 546install-sid @var{your-sid} 547@end smallexample 548 549@noindent 550where @var{your-sid} is the identification code you received with 551@w{@code{send-pr}}. @code{send-pr} automatically inserts this value 552into 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 556Place the following line in 557@w{@file{@var{prefix}/lib/emacs/lisp/default.el}}, or instruct your 558users 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 565Create 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 569where these aliases should point. For instance, edit your mail aliases 570file to contain something like: 571 572@smallexample 573# support sites; for use with send-pr 574cygnus-gnats: bugs@@cygnus.com # Cygnus Support 575bumblebee-gnats: bumblebugs@@bumblebee.com # Bumblebee Inc. 576mycompany-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 582send-pr cygnus 583send-pr bumblebee 584send-pr @var{site}@dots{} 585@end smallexample 586 587@noindent 588@code{send-pr} also uses @var{site} to determine the categories of 589problems 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 603Support 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 607send-pr @var{site} 608@end smallexample 609 610@noindent 611the Problem Report goes to the address noted in the @file{aliases} file 612as @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 616C-u M-x send-pr 617@end smallexample 618 619@noindent 620You are prompted for @var{site}. 621 622@var{site} is also used to error-check the @samp{>Category:} field, as a 623precaution against sending mistaken information (and against sending 624information to the wrong site). 625 626You may also simply type 627 628@smallexample 629send-pr 630@end smallexample 631 632@noindent 633from the shell (or @w{@samp{M-x send-pr}} in Emacs), and the Problem 634Report you generate will be sent to the @var{site}, which is usually the 635site from which you received your distribution of @w{@code{send-pr}}. 636If you use @sc{gnats} at your own organization, the default is usually 637your local address for reporting problems. 638 639To change this, simply edit the file @file{Makefile} before installing 640and change the line 641 642@smallexample 643GNATS_SITE = @var{site} 644@end smallexample 645 646@noindent 647to 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 658