523 lines
19 KiB
Plaintext
523 lines
19 KiB
Plaintext
@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
|
|
* 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} 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}. 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 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 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)>
|
|
>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 --request-id
|
|
Sends a request for a @code{>Submitter-Id:} to the Support Site.
|
|
|
|
@item -L
|
|
@item --list
|
|
@cindex listing valid categories
|
|
Prints the list of valid @code{>Category:} values on standard output.
|
|
No mail is sent.
|
|
|
|
@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
|
|
|
|
@node Helpful hints
|
|
@section Helpful hints
|
|
@cindex helpful hints
|
|
@cindex Using and Porting 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
|