send-pr/doc/s-usage.texi

@c $FreeBSD$

@c This is the usage section for send-pr.  It is called as
@c chapter (Invoking send-pr) by send-pr.texi, and also as
@c section (Submitting Problem Reports) by gnats.texi (chapter/section
@c identifiers are adjusted accordingly)

@c FIXME!  This still seems jumbled...

You can invoke @code{send-pr} from a shell prompt, or from within
@sc{gnu} Emacs using @w{@samp{M-x send-pr}}.

@menu
* using send-pr::             Creating new Problem Reports
* send-pr in Emacs::          Using send-pr from within Emacs
* send-pr from the shell::    Invoking send-pr from the shell
* Submitting via e-mail::     Submitting a Problem Report via direct e-mail
* Helpful hints::
@end menu

@node using send-pr
@section Creating new Problem Reports

@c FIXME - this is a long node
Invoking @code{send-pr} presents a PR @dfn{template} with a number of
fields already filled in.  Complete the template as thoroughly 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 instructions for 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.  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
@code{send-pr} creates a standard mail header.  @code{send-pr} completes
all fields except the @samp{Subject:} line with default values.
(@xref{Fields,,Problem Report format}.)

@item @sc{gnats} fields
These are the informational fields that @sc{gnats} uses to route your
Problem Report to the responsible party for further action.  They should
be filled out as completely as possible.  (@xref{Fields,,Problem Report
format}.  Also see @ref{Helpful hints,,Helpful hints}.)
@end table

@ifset SENDPR
@noindent
For examples of a Problem Report template and complete Problem Report,
see @ref{An Example}.
@end ifset

The default template contains your preconfigured @samp{>Submitter-Id:}.
@code{send-pr} attempts to determine values for the @samp{>Originator:}
and @samp{>Organization:} fields (@pxref{Fields,,Problem Report
format}).  @code{send-pr} will set the @samp{>Originator:} field to
the value of the @code{NAME} environment variable if it has been set;
similarly, @samp{>Organization:} will be set to the value of @code{ORGANIZATION}.
@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.

You may submit problem reports to different Support Sites from the
default site by specifying the alternate site when you invoke
@code{send-pr}.  @xref{send-pr from the shell}.
Each @code{site} has its own list of categories for
which it accepts Problem Reports.
@c FIXME!  This should go in..
@c For a list of sites to whom @code{send-pr} is configured to send
@c Problem Reports, type @w{@samp{send-pr -S}}.
@ifset SENDPR
(@xref{default site,,Setting a default @var{site}}.)
@end ifset

@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.

The template begins with a comment section:

@cindex template comment section
@cindex comment section in the PR template
@smallexample
@group
SEND-PR: -*- send-pr  -*-
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: Using 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 contains a list of valid @code{>Category:} values for the
Support Site to whom you are submitting this Problem Report.  One (and
only one) of these values should be placed in the @code{>Category:}
field.
@ifset SENDPR
A complete sample bug report, from template to completed PR, is shown in
@ref{An Example}.  For a complete list of valid categories, type
@w{@samp{send-pr -L}} at your prompt.  @xref{Valid Categories,,Valid
Categories}, for a sample list of categories, .
@end ifset

@c FIXME.. this sounds awkward
The mail header is just below the comment section.  Fill out the
@samp{Subject:} field, if it is not already completed using the value of
@samp{>Synopsis:}.  The other mail header fields contain default values.

@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 on your local machine for the
Support Site you wish to submit this PR to.

The rest of the template contains @sc{gnats} fields.  Each field is
either automatically completed with valid information (such as your
@samp{>Submitter-Id:}) or contains a one-line instruction specifying the
information that field requires 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.  @xref{Helpful hints,,Helpful hints}, for suggestions as to
what kinds of information to include.

In this example, words in @emph{italics} are filled in with
pre-configured information:

@cindex @code{send-pr} fields
@smallexample
@group
>Submitter-Id: @emph{your submitter-id}
>Originator:   @emph{your name here}
>Organization:
    @emph{your organization}
>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]>
>Release:     <release number (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)>
>Fix:
       <how to correct or work around the problem, if known
        (multiple lines)>
@end group
@end smallexample

@cindex @code{Submitter-Id} field
@cindex @code{>Submitter-Id:}
When you finish editing the Problem Report, @code{send-pr} mails it 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{>Category:}.

@ifset SENDPR
Your copy of @code{send-pr} should have already been customized on
installation to reflect your @samp{>Submitter-Id:}.  (@xref{Installing
send-pr, , Installing @code{send-pr} on your system}.)  If you don't
know your @samp{>Submitter-Id:}, 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}. @emph{NOTE:} If you are using
send-pr to send problem reports to the FreeBSD Project, this version of
send-pr already has a customer ID in it and you do not need to request a
new one.
@end ifset

@cindex bad Problem Reports
@cindex errors
@cindex invalid Problem Reports
If your PR has an invalid value in one of the @sc{Enumerated} fields
(@pxref{Fields,,Problem Report format}), @code{send-pr} places the PR in
a temporary file named @samp{/tmp/pbad@var{nnnn}} on your machine.
@var{nnnn} is the process identification number given to your current
@code{send-pr} session.  If you are running @code{send-pr} from the
shell, you are prompted as to whether or not you wish to try editing the
same Problem Report again.  If you are running @code{send-pr} from
Emacs, the Problem Report is placed in the buffer
@w{@samp{*send-pr-error*}}; you can edit this file and then submit it
with

@smallexample
M-x gnats-submit-pr
@end smallexample

@cindex subsequent mail
@cindex other mail
@cindex appending PRs
@cindex saving related mail
@cindex related mail
Any further mail concerning this Problem Report should be carbon-copied
to the @sc{gnats} mailing address as well, with the category and
identification number in the @samp{Subject:} line of the message.

@smallexample
Subject: Re: PR @var{category}/@var{gnats-id}: @var{original message subject}
@end smallexample

@noindent
Messages which arrive with @samp{Subject:} lines of this form are
automatically appended to the Problem Report in the @samp{>Audit-Trail:}
field in the order received.

@c ---------------------------------------------------------------
@node send-pr in Emacs
@section Using @code{send-pr} from within Emacs
@cindex 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
(@pxref{Introduction,,Introduction,emacs,GNU Emacs}).

Call @code{send-pr} with @w{@samp{M-x send-pr}}.@footnote{If typing
@w{@samp{M-x send-pr}} doesn't work, see your system administrator for
help loading @code{send-pr} into Emacs.}  @code{send-pr} responds with a
Problem Report template preconfigured for the Support Site from which
you received @code{send-pr}.  (If you use @code{send-pr} locally, the
default Support Site is probably your local site.)

You may also submit problem reports to different Support Sites from the
default site.  To use this feature, invoke @code{send-pr} with

@smallexample
C-u M-x send-pr
@end smallexample

@code{send-pr} prompts you for the name of a @var{site}.  @var{site} is
an alias on your local machine which points to an alternate Support
Site.

@cindex Emacs
@code{send-pr} displays the template and prompts you in the minibuffer
with the line:
@smallexample
>Category: other
@end smallexample

@noindent
Delete the default value @samp{other} @emph{in the minibuffer} and
replace it with the keyword corresponding to your problem (the list of
valid categories is in the topmost section of the PR template).  For
example, if the problem you wish to report 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} and then type
@w{@samp{gcc[@key{RET}]}}.  @code{send-pr} replaces the line

@smallexample
>Category:       <name of the product (one line)>
@end smallexample

@noindent
in the template with

@smallexample
>Category:       gcc
@end smallexample

@noindent
and moves on to another field.

@cindex completion in Emacs
@cindex name completion in Emacs
@w{@code{send-pr}} provides name completion in the minibuffer.  For
instance, you can also type @w{@samp{gc[@key{TAB}]}}, and @code{send-pr}
attempts to complete the entry for you.  Typing @w{@samp{g[@key{TAB}]}}
may not have the same effect if several possible entries begin with
@samp{g}.  In that case @code{send-pr} cannot complete the entry because
it cannot determine whether you mean @samp{gcc} or, for example,
@samp{gdb}, if both of those are possible categories.
@w{@code{send-pr}} continues to prompt you for a valid entry until you
enter one.

@w{@code{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, @code{send-pr}
responds with @w{@samp{[No match]}} and allows you to change the entry
until it contains an acceptable value.  This avoids unusable information
(at least in these fields) and also avoids typographical errors which
could cause problems later.

@code{send-pr} prompts you for the following fields:

@c FIXME - should these go before the discussion on completion?
@example
@group
>Category:
>Confidential: (@emph{default}:  no)
>Severity:     (@emph{default}:  serious)
>Priority:     (@emph{default}:  medium)
>Class:        (@emph{default}:  sw-bug)
>Release:
>Synopsis:     (@emph{this value is copied to @code{Subject:}})
@end group
@end example

@noindent
After you complete these fields, @w{@code{send-pr}} places the cursor in
the @samp{>Description:} field 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.
@ifset SENDPR
@xref{An Example}, for a sample Problem Report.
@end ifset

@w{@samp{send-pr}} provides a few key bindings to make moving
around in a template buffer more simple:

@table @code
@item C-c C-f
@itemx M-x change-field
Changes the field under the cursor.  @code{edit-pr} prompts you for a
new value.

@item M-C-b
@itemx M-x gnats-backward-field
Moves the cursor to the beginning of the value of the current field.

@item M-C-f
@itemx M-x gnats-forward-field
Moves the cursor to the end of the value of the current field.

@item M-p
@itemx M-x gnats-previous-field
Moves the cursor back one field to the beginning of the value of the
previous field.

@item M-n
@itemx M-x gnats-next-field
Moves the cursor forward one field to the beginning of the value of the
next field.
@end table

@code{send-pr} takes over again when you type @samp{C-c C-c} to send the
message.  @code{send-pr} reports any errors in a separate buffer, which
remains in existence until you send the PR properly (or, of course,
until you explicitly kill the buffer).

For detailed instructions on using Emacs, see
@ref{Introduction,,,emacs,GNU Emacs}.

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

@c FIXME!  Add [ -S ] right after [ -L ]...
@smallexample
send-pr [ @var{site} ]
        [ -f @var{problem-report} | --file @var{problem-report} ]
        [ -t @var{mail-address} | --to @var{mail-address} ]
        [ --request-id ]
        [ -L | --list ] [ -P | --print ]
        [ -V | --version] [ -h | --help ]
@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 @sc{gnats} locally.
@ifset SENDPR
(@xref{default site,,Setting a default @var{site}}.)
@end ifset

Invoking @code{send-pr} with no options calls the editor named in your
environment variable @code{EDITOR} on a default PR template.  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} points to 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}
@itemx --file @var{problem-report}
Specifies 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{-},
@w{@code{send-pr}} reads from standard input.

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

@item -c @var{mail-address}
@itemx --cc @var{mail-address}
Places @var{mail-address} in the @code{Cc:} header field of the message
to be sent.

@item --request-id
Sends a request for a @code{>Submitter-Id:} to the Support Site.

@cindex listing valid categories
@item -L
@itemx --list
Prints the list of valid @code{>Category:} values on standard output.
No mail is sent.

@item -s @var{severity}
@itemx --severity @var{severity}
@cindex @code{send-pr} fields
Sets the initial value of the @code{>Severity:} field to @var{severity}.

@ignore
@item -S
@itemx --sites
Displays a list of valid @var{site} values on standard output.  No mail
is sent.
@end ignore

@item -P
@itemx --print
Displays the PR template.  If the variable @code{PR_FORM} is set in your
environment, the file it specifies is printed.  If @code{PR_FORM} is not
set, @code{send-pr} prints the standard blank form.  If the file
specified by @code{PR_FORM} doesn't exist, @code{send-pr} displays an
error message.  No mail is sent.

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

@item -h
@itemx --help
Displays a usage summary for @code{send-pr}.  No mail is sent.
@end table

@c -------------------------------------------------------------------------
@node Submitting via e-mail
@section Submitting a Problem Report via direct e-mail
@cindex Direct e-mail
@cindex Submitting a PR via e-mail
In addition to using @code{send-pr}, there is another way to submit a problem
report.  You can simply send an e-mail message to the support site.

To do this, look at the address in the @samp{To:} field of the @code{send-pr}
template.  When you send unformatted e-mail to this address, @sc{gnats}
processes the message as a new problem report, filling in as many fields from
defaults as it can:

@table @code
@item Synopsis
The @samp{>Synopsis} field is filled in by the @samp{Subject:} header.

@item Submitter ID
@sc{gnats} will try to derive the @samp{>Submitter} field from the address
in the @samp{From:} header.

@item Description
All of the text in the body of the e-mail message is put into the
@samp{>Description} field.  Each line of the text is indented by one space,
indicating that it is "quoted text" from the sender.
@end table

Other fields, such as category, version, severity, etc. are set to default
values (if the @sc{gnats} administrator has set them).

@c --------------------------------------------------------------------------
@node Helpful hints
@section 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 GNU CC}, by Richard Stallman.  This section contains
instructions on what kinds of information to include and what kinds of
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, 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 realization 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, etc.).

@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 contain lists
of known bugs in the Release Notes which come with the software; see
your system administrator if you don't have a copy of these.

@item
The more closely a PR adheres to the standard format, the less
interaction is required by a database administrator to route the
information to the proper place.  Keep in mind that anything that
requires human interaction also requires time that might be better spent
in actually fixing the problem.  It is therefore in everyone's best
interest that the information contained in a PR be as correct as
possible (in both format and content) at the time of submission.
@end itemize