xemacs-beta: man/gnats/s-usage.texi comparison

comparison man/gnats/s-usage.texi @ 112:48d667d6f17f r20-1b8

Import from CVS: tag r20-1b8

author	cvs
date	Mon, 13 Aug 2007 09:20:48 +0200
parents
children

comparison

equal deleted inserted replaced

-:164ab62060bf
+:48d667d6f17f
+@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} 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}.  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 (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}.
+@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
+@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

Mercurial > hg > xemacs-beta

comparison man/gnats/s-usage.texi @ 112:48d667d6f17f r20-1b8