InfoMagic Source Code 1993 July/THE_SOURCE_CODE_CD_ROM.iso/gnu/gnats-3.01/send-pr/send-pr.input

Text File | 1993-04-13 | 46.4 KB | 1,416 lines

@c -*-texinfo-*-

@c ---------------------------------------------------------------
@node Reporting problems
@chapter An introduction to @code{send-pr}
@cindex reporting problems
@cindex introduction
@cindex email addresses
@cindex addresses

@code{@value{NAMEUC}} uses electronic mail to begin processing reported problems
and support requests.  It also automatically forwards the report to
those responsible for the problem in question, and returns mail
acknowledging that the Problem Report (@dfn{PR}) was received.

All PRs should follow a specific format in order for @code{@value{NAMEUC}} to
handle them properly.  The easiest way to avoid format problems when
submitting bugs is to use the @code{send-pr} utility.  @code{send-pr}
invokes an editor on a default Problem Report template, attempting to
automatically fill in some fields with predefined values.  You then
complete the form with relevant information.  @code{send-pr} takes
over once you quit the editor, and electronically mails the completed
PR using your local @code{mail} program.  When a Problem Report is
received by @code{@value{NAMEUC}} at the support site, its state is considered
to be @dfn{open}.

In general, you can use any editor and mailer to submit valid Problem
Reports, as long as the format required by @code{@value{NAMEUC}} is preserved.
@code{send-pr} automates the process, however, and ensures that certain
fields necessary for automatic processing are present.  @code{send-pr}
is strongly recommended for all initial problem-oriented correspondence
with your support site.  The organization you submit Problem Reports to
will supply an address to which further information can be sent; the
person responsible for the category of the problem you report will
probably contact you direcly.

@ifset SENDPR
@menu
* States of Problem Reports::  The Life of a Problem Report
* Problem Report format::      Formatting Problem Reports
@end menu

@c ---------------------------------------------------------------
@node States of Problem Reports
@section The Life of a Problem Report
@cindex life-cycle of a Problem Report
@cindex states of Problem Reports
@cindex Problem Report states
@cindex automatic notification

Each PR goes through a defined series of states between origination and
closure, and is considered @dfn{active} until it has been resolved or
otherwise explicitly @dfn{closed}.  As the originator of a PR, you are
automatically notified of any state changes that occur as long as your
email address in the mail header is correct.

@table @dfn
@cindex @emph{open} bugs
@cindex initial state (@dfn{open})
@cindex state---@dfn{open}
@item open
This is the initial state of a Problem Report.  This means the PR has
been filed and the responsible person(s) notified.

@item analyzed
@cindex @emph{analyzed} state
@cindex state---@dfn{analyzed}
The bug has been analyzed by the responsible person.  The analysis
should contain a preliminary evaluation of the problem and an estimate
of the amount of time and resources necessary to solve the problem.  It
should also suggest possible workarounds.

@item suspended
@cindex @emph{suspended} state
@cindex state---@dfn{suspended}
Work on the problem has been postponed.  This happens if a timely
solution is not possible or is not cost-effective at the present time.
The PR continues to exist, though a solution is not being actively
sought.  If the problem cannot be solved at all, it should be closed
rather than suspended.

@item feedback
@cindex @emph{feedback} state
@cindex state---@dfn{feedback}
This state indicates that the problem has been solved, and you've been
given a patch or other fix.  The PR remains in this state until you
acknowledge that the solution works.

@item closed
@cindex @emph{closed} state
@cindex state---@dfn{closed}
@cindex final state (@dfn{closed})
A Problem Report is closed only when any changes to the software in
question have been documented, integrated and tested, and you've
confirmed the solution.
@end table

@c ---------------------------------------------------------------
@node Problem Report format
@section Problem Report format
@cindex Problem Report format
@cindex format
@cindex database similarities
@cindex fields

The format of a PR is designed to reflect the nature of @code{@value{NAMEUC}} as a
database; information is arranged into fields.  A ``PR'' can be
considered a record that is electronically entered into the @code{@value{NAMEUC}}
database.  Thus, the level a PR adheres to the standard format
determines the level of interaction that is required by a database
administrator to route the information to the proper place.  (Hint: Keep
in mind that anything that requires human interaction also requires time
that might be better spent in actually fixing the bug.  It is therefore
in the best interest of all parties involved that the information
contained in a PR be as correct as possible at the time of submission.)

The PR form has two main sections, the @dfn{mail header} and the
@dfn{problem report}.  Each has fields that must contain entries before
the PR can be considered complete.

@menu
* Mail Header fields::
* Problem Report fields::
@end menu

@c ----------------------
@node Mail Header fields
@subsection Mail Header fields
@cindex mail header fields
@cindex Internet standard RFC-822
A Problem Report may contain any mail header field described in the
Internet standard RFC-822.  However, only the fields which identify the
sender and the subject are required for @code{send-pr} to function
properly:

@table @code
@item To:
Automatically supplied by @code{send-pr}.  It is the preconfigured mail
address for the support site where the PR is sent.

@item Subject:
Complete this field with a terse description of the problem.

@item From:
Usually supplied automatically by your mailer; should contain your
electronic mail address.  (This is found via the environment variable
@code{LOGNAME}, or @code{USER} if @code{LOGNAME} is not present.)

@item Reply-To:
A return address to which electronic replies can be sent.  In most
cases, this is probably the same address as the @code{From:} field.
@end table

@c ----------------------
@node Problem Report fields
@subsection Problem Report fields
@cindex Problem Report fields

These fields should comprise the only text in the body of the message in
order to avoid confusion.

Problem Report fields begin with a keyword enclosed with `>' and `:', and
belong to one of three data types:

@table @asis
@cindex Problem Report data types
@item @sc{Enumerated}
One value out of a specific set of choices.  The value must be on the
same line as the keyword.  For each @sc{Enumerated} keyword, the
possible choices are listed in the template as a comment.

@item @sc{String}
One single line of text which must begin and end on the same line as the
keyword.

@item @sc{Text}
Text of any length may occur in this field.  @sc{Text} may span multiple
lines and may also include blank lines.  A @sc{Text} field ends only
when another keyword appears.
@end table

The level of completeness and correctness in the following fields when
the PR is submitted helps determine the speed and quality of the
solution to the problem.

@table @code
@cindex Problem Report fields - list
@item >Submitter-Id:
@cindex @samp{Submitter-Id} field
@cindex @samp{--request-id} option
(@sc{Enumerated}) A unique identification code assigned by your
support site.  It is used to identify all Problem Reports coming
from a particular site.  (If you don't have an identification code,
please use @samp{send-pr --request-id} to apply for one from your support
organization.  Problem Reports from those not affiliated with the
support organization should use the default value of @samp{net} for this
field.)

@item >Originator:
@cindex @samp{Originator} field
(@sc{String}) Your real name.  The default is the value of the
environment variable @code{NAME}; if this is not present, the contents
of the file @file{.fullname} in your home directory are used.  If
neither of these is present, the field is left blank.

@item >Organization:
@cindex @samp{Organization} field
(@sc{Text}) The name of your organization.  The default value is the
contents of the environment variable @code{ORGANIZATION}; if this
variable is not set, the information is sought in the following order:

@itemize @bullet
@item
if @code{DEFAULT_ORGANIZATION} was set when your local @code{send-pr}
was installed, this value is used; otherwise,

@item
if your home directory contains the file @file{.organization}, its
contents are used; otherwise,

@item
if your home directory contains the file @file{.signature}, its contents
are used; otherwise,

@item
the field is blank by default.
@end itemize

@item >Confidential:
@cindex @samp{Confidential} field
(@sc{Enumerated}) Use of this field depends on your relationship with
the support organization; contractual agreements often have provisions
for preserving confidentiality.  Conversely, a lack of a contract often
means that any data you provide will not be considered confidential.
Contact the support organization directly if this is an issue.

If your relationship to the support organization provides for
confidentiality, then if the value of this field is @samp{yes} the
support organization treats your PR as confidential; any code samples
you provide are not made publicly available (e.g., in regression test
suites).  The default value is @samp{yes}.

@item >Synopsis:
@cindex @samp{Synopsis} field
(@sc{String}) One-line summary of the problem.

@item >Severity:
@cindex @samp{Severity} field
(@sc{Enumerated}) The severity of the problem.  Accepted values are:

@table @code
@item critical
The product, component or concept is completely non-operational or some
essential functionality is missing.  No workaround is known.

@item serious
The product, component or concept is not working properly or significant
functionality is missing.  Problems that would otherwise be considered
@samp{critical} are rated @samp{serious} when a workaround is known.

@item non-critical
The product, component or concept is working in general, but lacks
features, has irritating behaviour, does something wrong, or doesn't
match its documentation.
@end table
The default value is @samp{serious}.
@sp 1

@item >Priority:
@cindex @samp{Priority} field
(@sc{Enumerated}) How soon a solution is required.  Accepted values are:

@table @code
@item high
A solution is needed as soon as possible.

@item medium
The problem should be solved in the next release of the software.

@item low
The problem should be solved in a future release.
@end table
@noindent
The default value is @samp{medium}.
@sp 1

@item >Category:
@cindex @samp{Category} field
(@sc{Enumerated}) The name of the product, component or concept where
the problem lies.  Your support organization provides a list of valid
categories.  Try @samp{send-pr -L} to see the listing provided with your
distribution.  For an example list, see @ref{Valid Categories}.

@sp 1
@item >Class:
@cindex @samp{Class} field
(@sc{Enumerated}) The class of a problem can be one of the following:

@table @code
@item support
A support problem or question.

@item sw-bug
A software bug.

@item doc-bug
A bug in the documentation.

@item change-request
A request for a change in behavior, etc.

@c THIS CLASS EXISTS BUT WILL NOT BE USED EXTERNALLY
@c @item mistaken
@c No bug, user error or misunderstanding.

@item duplicate (@var{pr-number})
Duplicate PR.  @var{pr-number} should be the number of the original PR.
@end table
@noindent
The default is @samp{sw-bug}.
@sp 1

@item >Release:
@cindex @samp{Release} field
(@sc{String}) Release number or version of the product, component or
concept.

@item >Environment:
@cindex @samp{Environment} field
(@sc{Text}) Description of the environment where the problem occured:
machine architecture, operating system, host and target types,
libraries, pathnames, etc.

@item >Description:
@cindex @samp{Description} field
(@sc{Text}) Precise description of the problem, including all
preconditions, inputs, outputs, conditions after the problem, and
symptoms.  Please feel free to provide any additional information you
think is important.  Include all the details that would be necessary for
someone else to recreate the problem you're submitting, however obvious.
Sometimes seemingly arbitrary or obvious information can point the way
toward a solution.  @xref{Helpful hints}, for the types of information
to include.

@item >How-To-Repeat:
@cindex @samp{How-To-Repeat} field
(@sc{Text}) Example code, input, or activities to reproduce the problem.
The support organization uses your example code both to reproduce the
problem and to test whether the problem is fixed.  Again, see
@ref{Helpful hints}, for helpful hints.
@end table

@end ifset
@c ---------------------------------------------------------------
@node Invoking send-pr
@chapter Editing and sending PRs
@cindex editing and sending PRs
@cindex sending PRs
@cindex invoking send-pr
@cindex using send-pr

Invoking @code{send-pr} presents a partially completed template with a
number of fields already filled in.  Complete the template as fully as
possible to make a useful bug report.  Submit only one bug with each PR.

@cindex template
A template consists of three sections:

@table @dfn
@item Comments
The top several lines of a blank template consist of a series of
comments that provide some basic information about completing the
Problem Report, as well as a list of valid entries for the
@samp{>Category:} field.  These comments are all preceded by the string
@samp{SEND-PR:} and are erased automatically when the PR is submitted.
Note that the instructional comments within @samp{<} and @samp{>} are
also removed.  (Only these comments are removed; lines you provide that
happen to have those characters in them, such as examples of shell-level
redirection, are not affected.)

@item Mail Header
A standard mail header is provided.  All fields except the
@samp{Subject:} line are filled with default values.

@item @code{send-pr} Fields
These are the informational fields that @code{@value{NAMEUC}} uses to route
your Problem Report to the responsible party for further action.
They should be filled out as completely as possible.
@end table

@noindent
An example template and complete Problem Report are provided in
@ref{An Example}.

The default template contains your preconfigured @samp{>Submitter-Id:}.
When you invoke @code{send-pr}, it attempts to determine values for the
@samp{>Originator:} and @samp{>Organization:} fields (@pxref{Problem
Report fields}).  @code{send-pr} also attempts to find out some
information about your system and architecture, and places this
information in the @samp{>Environment:} field if it finds any.

@code{send-pr} also provides the mail header section of the template
with default values in the @samp{To:}, @samp{From:}, and
@samp{Reply-To:} fields.  The @samp{Subject:} field is empty.

Above the main part of the template is a comment section, beginning
with the messages:

@cindex comment section
@smallexample
@group
SEND-PR: -*- text  -*-
SEND-PR: Lines starting with `SEND-PR' will be removed
SEND-PR: automatically as well as all comments (the text
SEND-PR: below enclosed in `<' and `>').
SEND-PR:
SEND-PR: Please consult the document `Reporting Problems
SEND-PR: With send-pr' if you are not sure how to fill out
SEND-PR: a problem report.
SEND-PR:
SEND-PR: Choose from the following categories:
@end group
@end smallexample

@noindent
and also containing a list of valid @code{>Category:} values.  One (and
only one) of these values should be placed in the @code{>Category:}
field.  A complete sample bug report, from template to completed PR, is
shown in @ref{An Example}.  @xref{Valid Categories, , Valid Categories},
for a sample list of categories, or for a complete list type
@kbd{send-pr -L} at your prompt.

The mail header is just below the comment section.  Fill out the
@samp{Subject:} field.  The @samp{To:} field will contain a default
value if you neglected to specify a @var{site} when invoking
@code{send-pr}.

@cindex mail header section
@smallexample
@group
To: @var{support-site}
Subject: @emph{complete this field}
From: @var{your-login}@@@var{your-site}
Reply-To: @var{your-login}@@@var{your-site}
X-send-pr-version: send-pr @value{VERSION}
@end group
@end smallexample

@noindent
where @var{support-site} is an alias for the support site you wish to
submit this PR to.

The rest of the template contains @code{@value{NAMEUC}} fields.  Each field is
either completed with valid information (such as your
@samp{>Submitter-Id:}) or contains a one-line instruction specifying the
information that field needs in order to be correct.  For example, the
@samp{>Confidential:} field expects a value of @samp{yes} or @samp{no},
and the answer must fit on one line; similarly, the @samp{>Synopsis:}
field expects a short synopsis of the problem, which must also fit on
one line.  Fill out the fields as completely as possible.

@cindex @code{send-pr} fields
@smallexample
@group
>Submitter-Id:   @var{submitter-id}
>Originator:    @var{your name here}
>Organization:
@var{your site here}
>Confidential:<[ yes | no ] (one line)>
>Synopsis:    <synopsis of the problem (one line)>
>Severity:    <[ non-critical | serious | critical ] (one line)>
>Priority:    <[ low | medium | high ] (one line)>
>Category:    <name of the product (one line)>
>Class:       <[sw-bug|doc-bug|change-request|support](one line)>
>Release:     <release number or tag (one line)>
>Environment:
         <machine, os, target, libraries (multiple lines)>

>Description:
       <precise description of the problem (multiple lines)>
>How-To-Repeat:
       <code/input/activities to reproduce (multiple lines)>
@end group
@end smallexample

@cindex @samp{Submitter-Id}
@cindex @samp{--request-id} option
When you're finished editing the Problem Report, @code{send-pr} sends
the completed PR to the address named in the @samp{To:} field in the
mail header.  @code{send-pr} checks that the complete form contains a
valid @samp{>Submitter-Id:} and a valid @samp{>Category:}.  Your copy of
@code{send-pr} should have already been customized on installation to
reflect your @samp{>Submitter-Id:} (@pxref{Installing send-pr, ,
Installing @code{send-pr} on your system}).  If you don't know your
@samp{>Submitter-Id:} value, you can request it using @w{@samp{send-pr
--request-id}}.  If your organization is not affiliated with the site
you send Problem Reports to, a good generic @samp{>Submitter-Id:} to use
is @samp{net}.

@cindex bad Problem Reports
@cindex errors
@cindex invalid Problem Reports
A PR which has a @samp{>Submitter-Id:} equal to @samp{unknown} or which
has an invalid @samp{>Category:} is left in a temporary file named
@samp{/tmp/pbad@var{nnnn}} on your machine, where @var{nnnn} is replaced
by the process id given to your current @code{send-pr} session.  An
error message is generated specifying the exact name of the bad file.
You can then edit this file and resubmit it with

@smallexample
send-pr -f @var{filename}
@end smallexample

Invoke @code{send-pr} from a shell prompt or from within @sc{gnu} Emacs
using @w{@kbd{M-x send-pr}}.

@menu
* Command line options::    Invoking send-pr from the shell
* send-pr within Emacs::    Using send-pr from within Emacs
@end menu

@node Command line options
@section Invoking @code{send-pr} from the shell
@cindex command line options
@cindex invoking @code{send-pr} from the shell
@cindex shell invocation

@smallexample
send-pr [ @var{site} ][ -f @var{problem-report} ] [ -t @var{mail-address} ]
        [ -L ] [ -p ] [ -P ] [ --request-id ] [ -V ]
@end smallexample

@var{site} is an alias on your local machine which points to an address
used by a support site.  If this argument is not present, the default
@var{site} is usually the site which you received @code{send-pr} from,
or your local site if you use @code{@value{NAMEUC}} locally.
(@xref{default site, , Setting a default @var{site}}.)

Invoking @code{send-pr} with no options calls the editor named in your
environment variable @code{EDITOR}.  If the environment variable
@code{PR_FORM} is set, its value is used as a file name which contains a
valid template.  If @code{PR_FORM} contains a missing or unreadable
file, or if the file is empty, @code{send-pr} generates an error message
and opens the editor on a default template.

@table @code
@item -f @var{problem-report}
@cindex @samp{-f @var{problem-report}} option
Use this option to specify a file, @var{problem-report}, where a
completed Problem Report already exists.  @code{send-pr} sends the
contents of the file without invoking an editor.  (If
@var{problem-report} is @samp{-}, @code{send-pr} reads from the
standard input; @code{send-pr} uses this feature internally.)

@item -t @var{mail-address}
@cindex @samp{-t @var{mail-address}} option
Sets the electronic mail address to receive the PR.  The default is
preset when @code{send-pr} is configured.  This option is not
recommended; instead, use the argument @var{site} on the command line.

@item -L
@cindex @samp{-L} option
@cindex Listing valid categories
This prints the list of valid @code{>Category:} values on standard
output.  No mail is sent.

@item -p
@cindex @samp{-p} option
Prints the standard blank template on the standard output.  You can
print this blank form and use it to generate forms to @sc{FAX} or
physically mail to the support site if electronic mail fails to get
through.  You can also complete some default fields, such as your
organization's name in the @samp{>Organization:} field, your
@samp{Submitter-Id:}, and details about your machine's architecture in
the @samp{>Environment:} field, and use it as a custom form.  Specify
@code{send-pr} to use this custom form by setting your environment
variable @code{PR_FORM} to the name of the customized file.  No mail is
sent when you use this option.

@item -P
@cindex @samp{-P} option
Prints out the template specified by the variable @code{PR_FORM} in your
environment.  If @code{PR_FORM} is not set, the standard blank form is
printed.  If the file specified by @code{PR_FORM} doesn't exist, an
error message is printed.  No mail is sent.

@item --request-id
@cindex @samp{--request-id} option
Specifying this option sends a request for a @code{>Submitter-Id:} to the
support site (or to the mail address specified either with the @samp{-t}
option or in the @samp{To:} field in the mail header).

@item -V
@itemx --version
@cindex @samp{-V} option
Displays the @code{send-pr} version number and a usage summary.  No mail
is sent.
@end table

@c ---------------------------------------------------------------
@node send-pr within Emacs
@section Using @code{send-pr} from within Emacs
@cindex @code{send-pr} within Emacs
@cindex invoking @code{send-pr} from Emacs
@cindex interactive interface

You can use an interactive @code{send-pr} interface from within @sc{gnu}
Emacs to fill out your Problem Report.  We recommend that you
familiarize yourself with Emacs before using this feature
@ifinfo
(@pxref{Introduction, , , emacs, GNU Emacs}).
@end ifinfo
@iftex
(see the Emacs manual, @cite{GNU Emacs}).
@end iftex

The interface is called with @kbd{M-x send-pr}.  The interactive
interface prompts you for input for certain fields and then places you
in an Emacs buffer so you can complete the fields specific to your
problem.  It also sets up a few extra key bindings for ease of use.

To start the interactive @code{send-pr}, type

@smallexample
M-x send-pr
@end smallexample

@noindent
from inside Emacs.  Emacs responds with a template specifying your
preconfigured template as described above.  You may also submit problem
reports to support sites different from the default site.  To use this
feature, invoke @code{send-pr} with

@smallexample
C-u @var{site} M-x send-pr
@end smallexample

@emph{Note:} if typing @kbd{M-x send-pr} doesn't work, see your system
administrator for help in loading @code{send-pr} in Emacs.  In short,
any users who wish to use the Emacs version of @code{send-pr} must
place the following line in their @file{.emacs} files:

@smallexample
(autoload 'send-pr "send-pr" "Submit a Problem Report." t)
@end smallexample

@noindent
For more details on installing @code{send-pr}, see @ref{Installing
send-pr, Installing @code{send-pr} on your system}.

@cindex Emacs
If you are using @kbd{M-x send-pr}, you are prompted in the minibuffer
with the line:
@smallexample
>Category: other
@end smallexample

@noindent
Delete the default value @samp{other} and replace it with the keyword
corresponding to your problem.  For example, if the problem you're
reporting has to do with the @sc{gnu} C compiler, and your support
organization accepts bugs submitted for this program under the category
@samp{gcc}, delete @samp{other} @emph{in the minibuffer} and then type
@kbd{gcc [@key{RET}]}.  Emacs replaces the
@smallexample
>Category:       <name of the product (one line)>
@end smallexample
@noindent
line in the template with
@smallexample
>Category:       gcc
@end smallexample
@cindex completion in Emacs
@noindent
and moves on to another field.

The @w{@kbd{M-x send-pr}} function provides completion as well; in the
above example you can also type @w{@kbd{gc[@key{TAB}]}}, and Emacs will
try to complete the entry for you.  Note that typing
@w{@kbd{g[@key{TAB}]}} may not have the same effect if there are several
possible entries beginning with @samp{g}.  In that case Emacs will not
be able to complete the entry because it can not know whether you meant
@samp{gcc} or, say, @samp{gas}, if both of those are possible
categories.  @w{@kbd{M-x send-pr}} continues to prompt you for a valid
entry until you enter one.

@kbd{M-x send-pr} prompts you interactively to enter each field for
which there is a range of specific choices.  If you attempt to enter a
value which is not in the range of acceptable entries, Emacs responds
with @w{@samp{[No match]}} and allows you to change the entry until it
contains an acceptable value.  This is an excellent way both to avoid
unusable information (at least in these enumerated fields) and also to
avoid typographical errors which could cause problems later.

The interactive mode prompts you for the following fields:

@table @code
@item >Category:
@item >Confidential: (@var{default}=@code{yes})
@item >Severity: (@var{default}=@code{serious})
@item >Priority: (@var{default}=@code{medium})
@item >Class: (@var{default}=@code{sw-bug})
@item >Release:
@end table

After you complete these fields, @kbd{M-x send-pr} places the cursor in
the @samp{Subject:} line of the mail header and displays the message
@smallexample
To send the problem report use: C-c C-c
@end smallexample
@noindent
in the minibuffer.  At this point, edit the file in the main buffer to
reflect your specific problem, putting relevant information in the
proper fields.  @xref{An Example}, for a sample Problem Report.

@kbd{M-x send-pr} provides a few key bindings to make it simpler to move
around in a template buffer.

@table @kbd
@item M-p
@itemx M-x @value{NAMELC}-previous-field
moves the cursor to the beginning of the previous field

@item M-n
@itemx M-x @value{NAMELC}-next-field
moves the cursor to the beginning of the next field

@item M-C-b
@itemx M-x @value{NAMELC}-backward-field
moves the cursor to the end of the previous field

@item M-C-f
@itemx M-x @value{NAMELC}-forward-field
moves the cursor to the end of the next field
@end table

@code{send-pr} takes over again when you type @kbd{C-c C-c} to send the
message.  Any errors are reported in a separate window.  This window
remains active until you send the PR properly (or, of course, until you
explicitly kill the window).

For detailed instructions for
using Emacs,
@ifinfo
@xref{Introduction, , , emacs, GNU Emacs}.
@end ifinfo
@iftex
see the Emacs manual, @cite{GNU Emacs}.
@end iftex

@c ---------------------------------------------------------------
@node Installing send-pr
@chapter Installing @code{send-pr} on your system
@cindex installation

If you receive @code{send-pr} as part of a larger software distribution,
it will most likely be automatically installed when the full
distribution is installed.  If you are using @code{@value{NAMEUC}} at
your site as well, you must decide where @code{send-pr} is to send bug
reports by default; see @ref{default site, , Setting a default
@var{site}}.

@menu
* installation::   installing `send-pr' by itself
* default site::   setting a default site
@end menu

@node installation
@section Installing @code{send-pr} by itself

The @code{send-pr} directory, is easily installed by itself by following
these steps (you may need @code{root} access in order to change the
@file{aliases} file and to install @code{send-pr}):

@enumerate 1
@item @emph{Unpack the distribution} into a directory which we will
refer to as @var{srcdir}.

@item @emph{Edit the @file{Makefile} to reflect local conventions.}@*
Specifically, you should edit the variable @samp{prefix} to alter the
installation location.  The default is @file{/usr/local}.  All files are
installed under @samp{prefix} (see below).

@item @emph{Run}
@smallexample
make all install [ info ] install-info [ clean ]
@end smallexample

@noindent
The targets mean the following:

@table @code
@item all
Builds @code{send-pr} and @code{install-sid}

@item install
Installs the following:

@table @code
@item install-sid
@itemx send-pr
into @file{@var{prefix}/bin}

@item send-pr.1
into @file{@var{prefix}/man/man1}

@item @var{site}
the list of valid @var{categories} for the support site you received
@code{send-pr} from, installed as
@w{@file{@var{prefix}/lib/@value{NAMELC}/@var{site}}}

@item send-pr.el
into @w{@file{@var{prefix}/lib/emacs/lisp}}
@end table

@item info (@emph{optional})
Builds @file{send-pr.info} from @file{send-pr.texi}@*
(@file{send-pr.info} is included with this distribution)

@item install-info
Installs @file{send-pr.info} into @w{@file{@var{prefix}/info}}

@item clean (@emph{optional})
Removes all intermediary build files that can be rebuilt from source
code
@end table

@item @emph{Run}
@smallexample
install-sid @var{your-sid}
@end smallexample

@noindent
where @var{your-sid} is the identification code you received with
@code{send-pr}.  @code{send-pr} will automatically insert this value
into the template field @samp{>Submitter-Id}.  If you've downloaded
@code{send-pr} from the Net, use @samp{net} for this value.

@item @emph{Any users who wish to use the Emacs version of
@code{send-pr}} must place the following line in their @file{.emacs}
files:

@smallexample
(autoload 'send-pr "send-pr" "Submit a Problem Report." t)
@end smallexample

@item @emph{Create a mail alias} for the support site you received
@code{send-pr} from, and for every site with which you wish to use
@code{send-pr} to communicate, each with a suffix of @samp{-@value{NAMELC}}.  The
support site(s) will provide the correct addresses toward which these
aliases should point.  For instance, edit your mail aliases file to
contain something like:

@smallexample
# support sites; for use with send-pr
cygnus-@value{NAMELC}:     bugs@@cygnus.com            # Cygnus Support
bumblebee-@value{NAMELC}:  bumblebugs@@bumblebee.com   # Bumblebee Inc.
mycompany-@value{NAMELC}:  bugs@@my.company.com (@emph{if you use @code{@value{NAMEUC}} locally})
@end smallexample

@code{send-pr} automatically searches for these aliases when you type

@smallexample
send-pr cygnus
send-pr bumblebee
send-pr @var{site}@dots{}
@end smallexample

@noindent
@code{send-pr} also uses @var{site} to determine the categories of bugs
the site in question accepts by looking in

@smallexample
@var{prefix}/lib/@value{NAMELC}/@var{site}
@end smallexample

@end enumerate

@node default site
@section Setting a default @var{site}

@code{send-pr} is capable of sending bug reports to any number of
support sites via mail aliases which have @samp{-@value{NAMELC}}
appended them.  @code{send-pr} automatically appends the suffix, so that
when you type

@smallexample
send-pr @var{site}
@end smallexample

@noindent
the bug report will go to the address noted in the @file{aliases} file
as @samp{@var{site}-@value{NAMELC}}.  This is done in the Emacs version
of @code{send-pr} by invoking the program with

@smallexample
C-u @var{site} M-x send-pr
@end smallexample

@noindent
This value is also used to error-check the @samp{>Category:} field, as a
precaution against sending mistaken information (and against sending
information to the wrong site).

You may also simply type

@smallexample
send-pr
@end smallexample

@noindent
from the shell (or simply ``@kbd{M-x send-pr}'' in Emacs), and the
problem report you generate will be sent to the @dfn{default} site,
which is usually the site from which you received your distribution of
@code{send-pr}.  If you use @code{@value{NAMEUC}} at your own
organization, the default is your local bug-reporting address.

To change this, simply edit the file @file{Makefile} before installing
and change the line

@smallexample
@value{NAMEUC}_SITE = @var{site}
@end smallexample

@noindent
to reflect the site you wish to send PRs to by default.  Again,
@code{send-pr} automatically appends the @samp{-@value{NAMELC}} to the
@var{site} given on the command line.

@c ---------------------------------------------------------------
@node Helpful hints
@chapter Helpful hints
@cindex helpful hints
@cindex Using and Porting @sc{gnu} CC
@cindex effective problem reporting
@cindex kinds of helpful information
@cindex information to submit
@cindex Report all the facts!

There is no orthodox standard for submitting effective bug reports,
though you might do well to consult the section on submitting bugs for
@sc{gnu} @code{gcc} in @ref{Bugs, , Reporting Bugs, gcc, Using and
Porting @sc{gnu} CC}, by Richard Stallman, for information that can
typically be useful as well as mistakes to avoid.

In general, common sense (assuming such an animal exists) dictates the
kind of information that would be most helpful in tracking down and
resolving problems in software.
@itemize @bullet
@item
Include anything @emph{you} would want to know if you were looking at
the report from the other end.  There's no need to include every minute
detail about your environment (users have been known to provide the
values of every variable in their environments), although anything that
might be different from someone else's environment should be included
(your path, for instance).

@item
Narratives are often useful, given a certain degree of restraint.  If a
person responsible for a bug can see that A was executed, and then B and
then C, knowing that sequence of events might trigger the finding of an
intermediate step that was missing, or an extra step that might have
changed the environment enough to cause a visible problem.  Again,
restraint is always in order (``I set the build running, went to get a
cup of coffee (Columbian, cream but no sugar), talked to Sheila on the
phone, and then THIS happened@dots{}'') but be sure to include anything
relevant.

@item
Richard Stallman writes, ``The fundamental principle of reporting bugs
usefully is this: @strong{report all the facts}.  If you are not sure
whether to state a fact or leave it out, state it!''  This holds true
across all problem reporting systems, for computer software or social
injustice or motorcycle maintenance.  It is especially important in the
software field due to the major differences seemingly insignificant
changes can make (a changed variable, a missing semicolon).

@item
Submit only @emph{one} problem with each Problem Report.  If you have
multiple problems, use multiple PRs.  This aids in tracking each problem
and also in analyzing the problems associated with a given program.

@item
It never hurts to do a little research to find out if the bug you've
found has already been reported.  Most software releases will have lists
of known bugs in the Release Notes which should have come with the
software; see your system administrator if you don't have a copy of
these.
@end itemize

@c -----------------------------
@node An Example
@chapter An Example
@cindex an example
@cindex example PR
@cindex Cygnus Support
@cindex @sc{gnu} software support

Cygnus Support in Mountain View, CA, is a heavy user of
@code{@value{NAMEUC}} and @code{send-pr}.  As a support company, Cygnus
finds problem tracking to be a crucial part of everyday business.
Cygnus mainly supports the @sc{gnu} compiling tools, including
@code{@value{NAMEUC}} and @code{send-pr}, over several Un*x and
Un*x-like platforms, and is an example of @code{@value{NAMEUC}} in
action.

With each shipment of the Cygnus Developer's Toolkit, customers receive
the latest version of @code{send-pr}, which contains an up-to-date
listing of valid categories (values for the @code{>Category:} field).
Using these tools, Cygnus' customers can communicate their problems to
Cygnus effectively and receive automatic confirmation of receipt as well
as notification of changes in the status of their reported problems.
Much of Cygnus' support mechanism relies on electronic mail.

As an example, let's pretend we're a customer of Cygnus Support, and
that we're having a problem with some of our software.

Assume that we're getting an error in our bifrabulator program wherein
the prestidigitation routines don't match with the whatsitsname.  We've
made sure we're following the rules of the program and checked the
Release Notes from Cygnus and found that the bug isn't already known.
In other words, we're pretty sure we've found a bug.

@cindex Imaginary Software, Ltd.
Our first step is to call @code{send-pr}.  It really doesn't matter
whether we use @code{send-pr} from the shell or from within Emacs.
Indeed, if we use Emacs as a primary editor, calling @code{send-pr} from
the shell is likely to start @code{send-pr} in an Emacs buffer anyway.
So, since our company, @emph{Imaginary Software, Ltd.}, is a heavy user
of @sc{gnu} software, we're pretty familiar with Emacs, so from within
Emacs we type
@smallexample
M-x send-pr
@end smallexample
@noindent
and we're greeted with the following screen:

@cindex default PR template
@cindex example of a default template
@cartouche
@smallexample
SEND-PR: -*- text  -*-
SEND-PR: Lines starting with `SEND-PR' will be removed
SEND-PR: automatically as well as all comments (the text
SEND-PR: below enclosed in `<' and `>').
SEND-PR: Please consult the manual if you are not sure
SEND-PR: how to fill out a problem report.
SEND-PR:
SEND-PR: Choose from the following categories:
SEND-PR:
SEND-PR:           bfd       binutils  bison
SEND-PR: byacc     clib      config    cvs         diff
SEND-PR: doc       emacs     flex      g++         gas
SEND-PR: gcc       gdb       glob      gprof       grep
SEND-PR: info      ispell    kerberos  ld          libg++
SEND-PR: libiberty make      makeinfo  mas         newlib
SEND-PR: other     patch     rcs       readline    send-pr
SEND-PR: test      texindex  texinfo   texinfo.tex
SEND-PR: bifrabulator  <---@emph{note: this one is fake}
SEND-PR:
To: cygnus-bugs@@cygnus.com
Subject:
From: jeffrey@@imaginary.com
Reply-To: jeffrey@@imaginary.com
X-send-pr-version: send-pr @value{VERSION}

>Submitter-Id:  imaginary
>Originator:    Jeffrey Osier
>Organization:
Imaginary Software, Ltd.
>Confidential:  <[ yes | no ] (one line)>
>Synopsis:      <synopsis of the problem (one line)>
>Severity:      <[ non-critical | serious | critical ] (one line)>
>Priority:      <[ low | medium | high ] (one line)>
>Category:      <name of the product (one line)>
>Class:         <[sw-bug|doc-bug|change-request|support](oneline)>
>Release:       <release number or tag (one line)>
>Environment:
         <machine, os, target, libraries (multiple lines)>
System: SunOS imaginary.com 4.1.1 1 sun4
Architecture: sun4

>Description:
       <precise description of the problem (multiple lines)>
>How-To-Repeat:
       <code/input/activities to reproduce (multiple lines)>

@iftex
@hrule
@end iftex
-----Emacs: *send-pr*   (send-pr Fill)----All------------------
@iftex
@hrule
@end iftex
>Category: other[]
@end smallexample
@end cartouche
@page
We know from past experience that we need to set certain information into
each field, so we compile all the information we know about our problem.
We have some sample code which we know should work, even though it
doesn't, so we'll include that.  Below is the completed PR; we send this
using @kbd{C-c C-c}.  (The comments have been truncated).

@cindex completed Problem Report
@cindex example of a completed PR
@cartouche
@smallexample
SEND-PR: Lines starting with `SEND-PR' will be removed
SEND-PR: automatically as well as all comments (the text
SEND-PR: @dots{}
SEND-PR:
To: cygnus-bugs@@cygnus.com
Subject: bifrabulator routines don't match
From: jeffrey@@imaginary.com
Reply-To: jeffrey@@imaginary.com
X-send-pr-version: send-pr @value{VERSION}

>Submitter-Id:  imaginary
>Originator:    Jeffrey Osier
>Organization:
Imaginary Software, Ltd.
>Confidential:  no
>Synopsis:      bifrabulator routines don't match
>Severity:      serious
>Priority:      medium
>Category:      bifrabulator
>Class:         sw-bug
>Release:       progressive-930101
>Environment:
System: SunOS imaginary.com 4.1.1 1 sun4
Architecture: sun4 (SPARC)

>Description:
   the following code I fed into the bifrabulator came back
   with a strange error.  apparently, the prestidigitation
   routine doesn't match with the whatsitsname in all cases.

>How-To-Repeat:
   call the bifrabulator on the following code.
   @var{code sample@dots{}}


@iftex
@hrule
@end iftex
-----Emacs: *send-pr*   (send-pr Fill)----All------------------
@iftex
@hrule
@end iftex
To send the problem report use: C-c C-c
@end smallexample
@end cartouche

We type @kbd{C-c C-c}, and off it goes.  Now, we depend on Cygnus
Support to figure out the answer to our problem.

Soon afterward, we get the following message from Cygnus:

@smallexample
@group
From: @value{NAMELC} (@value{NAMEUC} management)
Sender: @value{NAMELC}-admin
Reply-To: hacker@@cygnus.com
To: jeffrey@@imaginary.com
Subject: Re: bifrabulator/1425: routines don't match

Thank you very much for your problem report.
It has the internal identification: g++/1425.
The individual assigned to look at your bug is:  hacker
(F.B. Hacker)

Category: bifrabulator
Responsible: hacker
Synopsis: bifrabulator routines don't match
Arrival-Date: Sat Feb 30 03:12:55 1993
@end group
@end smallexample

@noindent
This is our ``receipt'' that the bug has been accepted and forwarded to
the responsible party.

@noindent
A while later, we get the analysis:

@smallexample
@group
To:  jeffrey@@imaginary.com
From:  hacker@@cygnus.com
Subject:  Re: bifrabulator/1425: routines don't match
Reply-To: hacker@@cygnus.com

Got your message, Jeff.  It seems that the bifrabulator was
confusing the prestidigitation routines with the realitychecker
when lexically parsing the whatsitsname.

I'm working on robustisizing the bifrabulator now.

How about lunch next week?
--
F.B. Hacker
Cygnus Support, Mountain View, CA  415 903 1400
#include <std-disclaimer.h>
@end group
@end smallexample

@noindent
About the same time, we get another message from Cygnus.

@cindex state change example
@cindex example of a state change
@smallexample
@group
From: hacker@@cygnus.com
To:  jeffrey@@imaginary.com
Subject:  Re: bifrabulator/1425: doesn't match prestidig
Reply-To:  hacker@@cygnus.com


             `F.B. Hacker' changed the state to `analyzed'.

State-Changed-From-To: open-analyzed
State-Changed-By: hacker
State-Changed-When: Fri Feb 31 1993 08:59:16 1993
State-Changed-Why:
    figured out the problem, working on a patch this afternoon
--
F.B. Hacker
Cygnus Support, Mountain View, CA  415 903 1400
#include <std-disclaimer.h>
@end group
@end smallexample

@noindent
The bug has now been analyzed, and Cygnus is working on a solution.
Sometime later, we get more mail from F.B.:

@smallexample
@group
To:  jeffrey@@imaginary.com
From:  hacker@@cygnus.com
Subject:  Re: bifrabulator/1425: routines don't match
Reply-To: hacker@@cygnus.com

There's a patch now that you can ftp over and check out.

Hey, that joke you sent me was great!  The one about the
strings walking into a bar...  my boss laughed for an hour!
--
F.B. Hacker
Cygnus Support, Mountain View, CA  415 903 1400
#include <std-disclaimer.h>
@end group
@end smallexample
@sp 2
@smallexample
@group
From: hacker@@cygnus.com
To:  jeffrey@@imaginary.com
Subject:  Re: bifrabulator/1425: doesn't match prestidig
Reply-To:  hacker@@cygnus.com


             `F.B. Hacker' changed the state to `feedback'.

State-Changed-From-To: analyzed-feedback
State-Changed-By: hacker
State-Changed-When: Fri Feb 31 1993 23:43:16 1993
State-Changed-Why:
    got the patch finished, notified Jeff at Imaginary Software
--
F.B. Hacker
Cygnus Support, Mountain View, CA  415 903 1400
#include <std-disclaimer.h>
@end group
@end smallexample

@noindent
The bug has gone into @dfn{feedback} status now, until we get the patch,
install it and test it.  When everything tests well, we can mail F.B.
back and tell him the bug's been fixed, and he can change the state of
the PR from @dfn{feedback} to @dfn{closed}.

Following is a list of valid @samp{>Category:} entries that are
supported by Cygnus.

@menu
* Valid Categories::    A listing of Cygnus' valid categories
@end menu

@c -----------------------------
@node Valid Categories
@unnumberedsec Valid Categories
@cindex valid categories
@cindex example of a list of valid categories

@table @code
@item bfd
@sc{gnu} binary file descriptor library.

@item bifrabulator
This one doesn't actually exist.

@item binutils
@sc{gnu} utilities for binary files (@code{ar}, @code{nm}, @code{size}@dots{}).

@item bison
@sc{gnu} parser generator.

@item byacc
Free parser generator.

@item config
Cygnus Support Software configuration and installation.

@item cvs
Concurrent Version System.

@item diff
@sc{gnu} @code{diff} program.

@item doc
Documentation and manuals.

@item emacs
@sc{gnu} Emacs editor and related functions.

@item flex
@sc{gnu} lexical analyzer.

@item g++
@sc{gnu} C++ compiler.

@item gas
@sc{gnu} assembler.

@item gcc
@sc{gnu} C compiler.

@item gdb
@sc{gnu} source code debugger.

@item glob
The filename globbing functions.

@item gprof
@sc{gnu} profiler.

@item grep
@sc{gnu} @code{grep} program.

@item info
@sc{gnu} @code{info} hypertext reader.

@item ispell
@sc{gnu} spelling checker.

@item kerberos
Kerberos authentication system.

@item ld
@sc{gnu} linker.

@item libc
Cygnus Support C Support Library.

@item libg++
@sc{gnu} C++ class library.

@item libiberty
@sc{gnu} @samp{libiberty} library.

@item libm
Cygnus Support C Math Library.

@item make
@sc{gnu} @code{make} program.

@item makeinfo
@sc{gnu} utility to build Info files from Texinfo documents.

@item mas
@sc{gnu} Motorola syntax assembler.

@item newlib
Cygnus Support C Support and Math Libraries.

@item patch
@sc{gnu} bug patch program.

@item @value{NAMELC}
@sc{gnu} Problem Report Management System.

@item rcs
Revision Control System.

@item readline
@sc{gnu} @code{readline} library.

@item send-pr
@sc{gnu} Problem Report submitting program.

@item test
Category to use when testing @code{send-pr}.

@item texindex
@sc{gnu} documentation indexing utility.

@item texinfo
@sc{gnu} documentation macros.

@item other
Anything which is not covered by the above categories.
@end table