diff options
author | Peter Wemm <peter@FreeBSD.org> | 1995-12-30 19:02:48 +0000 |
---|---|---|
committer | Peter Wemm <peter@FreeBSD.org> | 1995-12-30 19:02:48 +0000 |
commit | a5b996a7ecea192e05c848269fbfb40c1e7c50ef (patch) | |
tree | b43d0e66d9963acc026a6322b81fd219d273736b /gnu/usr.bin/send-pr | |
parent | df2fbf15a2e56a16c3b54b93a3369b662b6f20e5 (diff) | |
download | src-a5b996a7ecea192e05c848269fbfb40c1e7c50ef.tar.gz src-a5b996a7ecea192e05c848269fbfb40c1e7c50ef.zip |
recording cvs-1.6 file death
Notes
Notes:
svn path=/cvs2svn/branches/ATT/; revision=13122
Diffstat (limited to 'gnu/usr.bin/send-pr')
-rw-r--r-- | gnu/usr.bin/send-pr/send-pr.info | 1604 | ||||
-rw-r--r-- | gnu/usr.bin/send-pr/send-pr.texi | 657 |
2 files changed, 0 insertions, 2261 deletions
diff --git a/gnu/usr.bin/send-pr/send-pr.info b/gnu/usr.bin/send-pr/send-pr.info deleted file mode 100644 index 4e98715b9ca9..000000000000 --- a/gnu/usr.bin/send-pr/send-pr.info +++ /dev/null @@ -1,1604 +0,0 @@ -This is Info file send-pr.info, produced by Makeinfo-1.55 from the -input file ./send-pr.texi. - -START-INFO-DIR-ENTRY -* send-pr:: Reporting problems--using send-pr -END-INFO-DIR-ENTRY - - Copyright (C) 1993 Free Software Foundation, Inc. - - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. - - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided also -that the entire resulting derived work is distributed under the terms -of a permission notice identical to this one. - - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions. - - -File: send-pr.info, Node: Top, Next: send-pr in detail, Prev: (DIR), Up: (DIR) - -Overview -******** - - This manual documents `send-pr', version 3.2, which uses electronic -mail to submit support questions and problem reports to a central -Support Site. No body of work is perfect, and support organizations -understand this; `send-pr' is designed to allow users who have problems -to submit reports of these problems to sites responsible for supporting -the products in question, in a defined form which can be read by an -electronically managed database. - - `send-pr' is part of a suite of programs known collectively as -GNATS, the GNU Problem Report Management System. GNATS consists of -several programs which, used in concert, formulate and partially -administer a database of "Problem Reports", or "PRs", at a central -Support Site. A PR goes through several states in its lifetime; GNATS -tracks the PR and all information associated with it through each state -and finally acts as an archive for PRs which have been "closed". - - Because `send-pr' exists as a shell (`/bin/sh') script and as an -Elisp file for use with GNU Emacs, it can be used from any machine on -your network which can run a shell script and/or Emacs. - - In general, you can use any editor and mailer to submit valid Problem -Reports, as long as the format required by GNATS is preserved. -`send-pr' automates the process, however, and ensures that certain -fields necessary for automatic processing are present. `send-pr' is -strongly recommended for all initial problem-oriented correspondence -with your Support Site. The organization you submit Problem Reports to -supplies an address to which further information can be sent; the person -responsible for the category of the problem you report contacts you -directly. - -* Menu: - -* send-pr in detail:: Details about send-pr and GNATS -* Invoking send-pr:: Editing and sending PRs -* An Example:: A working example -* Installing send-pr:: Installing send-pr on your system -* Index:: - - -File: send-pr.info, Node: send-pr in detail, Next: Invoking send-pr, Prev: Top, Up: Top - -Details about send-pr and GNATS -******************************* - - A "Problem Report" is a message that describes a problem you are -having with a body of work. `send-pr' organizes this message into a -form which can be understood and automatically processed by GNATS, the -GNU Problem Report Management System. A Problem Report is organized -into "fields" which contain data describing you, your organization, and -the problem you are announcing (*note Problem Report format: Fields.). -Problem Reports go through several defined states in their lifetimes, -from "open" to "closed" (*note States of Problem Reports: States.). - -* Menu: - -* States:: States of Problem Reports -* Fields:: Problem Report format - - -File: send-pr.info, Node: States, Next: Fields, Up: send-pr in detail - -States of Problem Reports -========================= - - Each PR goes through a defined series of states between origination -and closure. The originator of a PR receives notification -automatically of any state changes. - -"open" - The initial state of a Problem Report. This means the PR has been - filed and the responsible person(s) notified. - -"analyzed" - The responsible person has analyzed the problem. 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. - -"feedback" - The problem has been solved, and the originator has been given a - patch or other fix. The PR remains in this state until the - originator acknowledges that the solution works. - -"closed" - A Problem Report is closed ("the bug stops here") only when any - changes have been integrated, documented, and tested, and the - submitter has confirmed the solution. - -"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. - - -File: send-pr.info, Node: Fields, Prev: States, Up: send-pr in detail - -Problem Report format -===================== - - The format of a PR is designed to reflect the nature of GNATS as a -database. Information is arranged into "fields", and kept in -individual records (Problem Reports). - - Problem Report fields are denoted by a keyword which begins with `>' -and ends with `:', as in `>Confidential:'. Fields belong to one of -three data types: - -ENUMERATED - One of a specific set of values, which vary according to the - field. The value for each keyword must be on the same line as the - keyword. These values are not configurable (yet). - - For each ENUMERATED keyword, the possible choices are listed in the - `send-pr' template as a comment. The following fields are - ENUMERATED format; see the descriptions of fields below for - explanations of each field in detail: - - >Confidential: >Severity: >Priority: - >Class: >State: >Number: - -TEXT - One single line of text which must begin and end on the same line - (i.e., before a newline) as the keyword. See the descriptions of - fields below for explanations of each field in detail. The - following fields are TEXT format: - - >Submitter-Id: >Originator: >Synopsis: - >Category: >Release: >Responsible: - >Arrival-Date: - -MULTITEXT - Text of any length may occur in this field. MULTITEXT may span - multiple lines and may also include blank lines. A MULTITEXT field - ends only when another keyword appears. See the descriptions of - fields below for explanations of each field in detail. - - The following fields are MULTITEXT format: - - >Organization: >Environment: >Description: - >How-To-Repeat: >Fix: >Audit-Trail: - >Unformatted: - - A Problem Report contains two different types of fields: "Mail -Header" fields, which are used by the mail handler for delivery, and -"Problem Report" fields, which contain information relevant to the -Problem Report and its submitter. A Problem Report is essentially a -specially formatted electronic mail message. - - The following is an example Problem Report. Mail headers are at the -top, followed by GNATS fields, which begin with `>' and end with `:'. -The `Subject:' line in the mail header and the `>Synopsis:' field are -usually duplicates of each other. - - Message-Id: MESSAGE-ID - Date: DATE - From: ADDRESS - Reply-To: ADDRESS - To: BUG-ADDRESS - Subject: SUBJECT - - >Number: GNATS-ID - >Category: CATEGORY - >Synopsis: SYNOPSIS - >Confidential: yes *or* no - >Severity: critical, serious, *or* non-critical - >Priority: high, medium *or* low - >Responsible: RESPONSIBLE - >State: open, analyzed, suspended, feedback, *or* closed - >Class: sw-bug, doc-bug, change-request, support, - *or* duplicate - >Submitter-Id: SUBMITTER-ID - >Arrival-Date: DATE - >Originator: NAME - >Organization: ORGANIZATION - >Release: RELEASE - >Environment: - ENVIRONMENT - >Description: - DESCRIPTION - >How-To-Repeat: - HOW-TO-REPEAT - >Fix: - FIX - >Audit-Trail: - APPENDED-MESSAGES... - State-Changed-From-To: FROM-TO - State-Changed-When: DATE - State-Changed-Why: - REASON - Responsible-Changed-From-To: FROM-TO - Responsible-Changed-When: DATE - Responsible-Changed-Why: - REASON - >Unformatted: - MISCELLANEOUS - -* Menu: - -* Mail header fields:: -* Problem Report fields:: - - -File: send-pr.info, Node: Mail header fields, Next: Problem Report fields, Up: Fields - -Mail header fields ------------------- - - 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 by `send-pr': - -`To:' - The preconfigured mail address for the Support Site where the PR - is to be sent, automatically supplied by `send-pr'. - -`Subject:' - A terse description of the problem. This field normally contains - the same information as the `>Synopsis:' field. - -`From:' - Usually supplied automatically by the originator's mailer; should - contain the originator's electronic mail address. - -`Reply-To:' - A return address to which electronic replies can be sent; in most - cases, the same address as the `From:' field. - - -File: send-pr.info, Node: Problem Report fields, Prev: Mail header fields, Up: Fields - -Problem Report fields ---------------------- - -Field descriptions ------------------- - - The following fields are present whenever a PR is submitted via the -program `send-pr'. GNATS adds additional fields when the PR arrives at -the Support Site; explanations of these follow this list. - -`>Submitter-Id:' - (TEXT) A unique identification code assigned by the Support Site. - It is used to identify all Problem Reports coming from a particular - site. (Submitters without a value for this field can invoke - `send-pr' with the `--request-id' option to apply for one from the - support organization. Problem Reports from those not affiliated - with the support organization should use the default value of `net' - for this field.) - -`>Originator:' - (TEXT) Originator's real name. The default is the value of the - originator's environment variable `NAME'. - -`>Organization:' - (MULTITEXT) The originator's organization. The default value is - set with the variable `DEFAULT_ORGANIZATION' in the `send-pr' - shell script. - -`>Confidential:' - (ENUMERATED) Use of this field depends on the originator's - relationship with the support organization; contractual agreements - often have provisions for preserving confidentiality. Conversely, - a lack of a contract often means that any data provided will not - be considered confidential. Submitters should be advised to - contact the support organization directly if this is an issue. - - If the originator's relationship to the support organization - provides for confidentiality, then if the value of this field is - `yes' the support organization treats the PR as confidential; any - code samples provided are not made publicly available (e.g., in - regression test suites). The default value is `yes'. - -`>Synopsis:' - (TEXT) One-line summary of the problem. `send-pr' copies this - information to the `Subject:' line when you submit a Problem - Report. - -`>Severity:' - (ENUMERATED) The severity of the problem. Accepted values include: - - `critical' - The product, component or concept is completely - non-operational or some essential functionality is missing. - No workaround is known. - - `serious' - The product, component or concept is not working properly or - significant functionality is missing. Problems that would - otherwise be considered `critical' are rated `serious' when a - workaround is known. - - `non-critical' - The product, component or concept is working in general, but - lacks features, has irritating behavior, does something - wrong, or doesn't match its documentation. The default value - is `serious'. - -`>Priority:' - (ENUMERATED) How soon the originator requires a solution. Accepted - values include: - - `high' - A solution is needed as soon as possible. - - `medium' - The problem should be solved in the next release. - - `low' - The problem should be solved in a future release. - - The default value is `medium'. - -`>Category:' - (TEXT) The name of the product, component or concept where the - problem lies. The values for this field are defined by the Support - Site. - -`>Class:' - (ENUMERATED) The class of a problem can be one of the following: - - `sw-bug' - A general product problem. (`sw' stands for "software".) - - `doc-bug' - A problem with the documentation. - - `change-request' - A request for a change in behavior, etc. - - `support' - A support problem or question. - - `duplicate (PR-NUMBER)' - Duplicate PR. PR-NUMBER should be the number of the original - PR. - - The default is `sw-bug'. - -`>Release:' - (TEXT) Release or version number of the product, component or - concept. - -`>Environment:' - (MULTITEXT) Description of the environment where the problem - occured: machine architecture, operating system, host and target - types, libraries, pathnames, etc. - -`>Description:' - (MULTITEXT) Precise description of the problem. - -`>How-To-Repeat:' - (MULTITEXT) Example code, input, or activities to reproduce the - problem. The support organization uses example code both to - reproduce the problem and to test whether the problem is fixed. - Include all preconditions, inputs, outputs, conditions after the - problem, and symptoms. Any additional important information - should be included. Include all the details that would be - necessary for someone else to recreate the problem reported, - however obvious. Sometimes seemingly arbitrary or obvious - information can point the way toward a solution. See also *Note - Helpful hints: Helpful hints. - -`>Fix:' - (MULTITEXT) A description of a solution to the problem, or a patch - which solves the problem. (This field is most often filled in at - the Support Site; we provide it to the submitter in case she has - solved the problem.) - -GNATS adds the following fields when the PR arrives at the Support Site: - -`>Number:' - (ENUMERATED) The incremental identification number for this PR. - - The `>Number:' field is often paired with the `>Category:' field as - - CATEGORY/NUMBER - - in subsequent email messages. This is for historical reasons, as - well as because Problem Reports are stored in subdirectories which - are named by category. - -`>State:' - (ENUMERATED) The current state of the PR. Accepted values are: - - `open' - The PR has been filed and the responsible person notified. - - `analyzed' - The responsible person has analyzed the problem. - - `feedback' - The problem has been solved, and the originator has been - given a patch or other fix. - - `closed' - The changes have been integrated, documented, and tested, and - the originator has confirmed that the solution works. - - `suspended' - Work on the problem has been postponed. - - The initial state of a PR is `open'. *Note States of Problem - Reports: States. - -`>Responsible:' - (TEXT) The person responsible for this category. - -`>Arrival-Date:' - (TEXT) The time that this PR was received by GNATS. The date is - provided automatically by GNATS. - -`>Audit-Trail:' - (MULTITEXT) Tracks related electronic mail as well as changes in - the `>State:' and `>Responsible:' fields with the sub-fields: - - `State-Changed-<From>-<To>: OLDSTATE>-<NEWSTATE' - The old and new `>State:' field values. - - `Responsible-Changed-<From>-<To>: OLDRESP>-<NEWRESP' - The old and new `>Responsible:' field values. - - `State-Changed-By: NAME' - `Responsible-Changed-By: NAME' - The name of the maintainer who effected the change. - - `State-Changed-When: TIMESTAMP' - `Responsible-Changed-When: TIMESTAMP' - The time the change was made. - - `State-Changed-Why: REASON...' - `Responsible-Changed-Why: REASON...' - The reason for the change. - - The `>Audit-Trail:' field also contains any mail messages received - by GNATS related to this PR, in the order received. - -`>Unformatted:' - (MULTITEXT) Any random text found outside the fields in the - original Problem Report. - - -File: send-pr.info, Node: Invoking send-pr, Next: An Example, Prev: send-pr in detail, Up: Top - -Editing and sending PRs -*********************** - - You can invoke `send-pr' from a shell prompt or from within GNU -Emacs using `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:: - - -File: send-pr.info, Node: using send-pr, Next: send-pr in Emacs, Up: Invoking send-pr - -Creating new Problem Reports -============================ - - Invoking `send-pr' presents a PR "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. - - A template consists of three sections: - -"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 - `>Category:' field. These comments are all preceded by the string - `SEND-PR:' and are erased automatically when the PR is submitted. - The instructional comments within `<' and `>' 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.) - -"Mail Header" - `send-pr' creates a standard mail header. `send-pr' completes all - fields except the `Subject:' line with default values. (*Note - Problem Report format: Fields.) - -"GNATS fields" - These are the informational fields that GNATS uses to route your - Problem Report to the responsible party for further action. They - should be filled out as completely as possible. (*Note Problem - Report format: Fields. Also see *Note Helpful hints: Helpful - hints.) - -For examples of a Problem Report template and complete Problem Report, -see *Note An Example::. - - The default template contains your preconfigured `>Submitter-Id:'. -`send-pr' attempts to determine values for the `>Originator:' and -`>Organization:' fields (*note Problem Report format: Fields.). -`send-pr' also attempts to find out some information about your system -and architecture, and places this information in the `>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 -`send-pr'. Each `site' has its own list of categories for which it -accepts Problem Reports. (*Note Setting a default SITE: default site.) - - `send-pr' also provides the mail header section of the template with -default values in the `To:', `From:', and `Reply-To:' fields. The -`Subject:' field is empty. - - The template begins with a comment section: - - 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: - -and also contains a list of valid `>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 `>Category:' field. A -complete sample bug report, from template to completed PR, is shown in -*Note An Example::. For a complete list of valid categories, type -`send-pr -L' at your prompt. *Note Valid Categories: Valid Categories, -for a sample list of categories, . - - The mail header is just below the comment section. Fill out the -`Subject:' field, if it is not already completed using the value of -`>Synopsis:'. The other mail header fields contain default values. - - To: SUPPORT-SITE - Subject: *complete this field* - From: YOUR-LOGIN@YOUR-SITE - Reply-To: YOUR-LOGIN@YOUR-SITE - X-send-pr-version: send-pr 3.2 - -where SUPPORT-SITE is an alias for the Support Site you wish to submit -this PR to. - - The rest of the template contains GNATS fields. Each field is -either automatically completed with valid information (such as your -`>Submitter-Id:') or contains a one-line instruction specifying the -information that field requires in order to be correct. For example, -the `>Confidential:' field expects a value of `yes' or `no', and the -answer must fit on one line; similarly, the `>Synopsis:' field expects -a short synopsis of the problem, which must also fit on one line. Fill -out the fields as completely as possible. *Note Helpful hints: Helpful -hints, for suggestions as to what kinds of information to include. - - In this example, words in *italics* are filled in with -pre-configured information: - - >Submitter-Id: *your submitter-id* - >Originator: *your name here* - >Organization: - *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)> - - When you finish editing the Problem Report, `send-pr' mails it to -the address named in the `To:' field in the mail header. `send-pr' -checks that the complete form contains a valid `>Category:'. - - Your copy of `send-pr' should have already been customized on -installation to reflect your `>Submitter-Id:'. (*Note Installing -`send-pr' on your system: Installing send-pr.) If you don't know your -`>Submitter-Id:', you can request it using `send-pr --request-id'. If -your organization is not affiliated with the site you send Problem -Reports to, a good generic `>Submitter-Id:' to use is `net'. - - If your PR has an invalid value in one of the ENUMERATED fields -(*note Problem Report format: Fields.), `send-pr' places the PR in a -temporary file named `/tmp/pbadNNNN' on your machine. NNNN is the -process identification number given to your current `send-pr' session. -If you are running `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 `send-pr' from Emacs, the Problem Report is placed -in the buffer `*send-pr-error*'; you can edit this file and then submit -it with - - M-x gnats-submit-pr - - Any further mail concerning this Problem Report should be -carbon-copied to the GNATS mailing address as well, with the category -and identification number in the `Subject:' line of the message. - - Subject: Re: PR CATEGORY/GNATS-ID: ORIGINAL MESSAGE SUBJECT - -Messages which arrive with `Subject:' lines of this form are -automatically appended to the Problem Report in the `>Audit-Trail:' -field in the order received. - - -File: send-pr.info, Node: send-pr in Emacs, Next: send-pr from the shell, Prev: using send-pr, Up: Invoking send-pr - -Using `send-pr' from within Emacs -================================= - - You can use an interactive `send-pr' interface from within GNU Emacs -to fill out your Problem Report. We recommend that you familiarize -yourself with Emacs before using this feature (*note Introduction: -(emacs)Introduction.). - - Call `send-pr' with `M-x send-pr'.(1) `send-pr' responds with a -Problem Report template preconfigured for the Support Site from which -you received `send-pr'. (If you use `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 `send-pr' with - - C-u M-x send-pr - - `send-pr' prompts you for the name of a SITE. SITE is an alias on -your local machine which points to an alternate Support Site. - - `send-pr' displays the template and prompts you in the minibuffer -with the line: - >Category: other - -Delete the default value `other' *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 GNU C compiler, -and your support organization accepts bugs submitted for this program -under the category `gcc', delete `other' and then type `gcc[RET]'. -`send-pr' replaces the line - - >Category: <name of the product (one line)> - -in the template with - - >Category: gcc - -and moves on to another field. - - `send-pr' provides name completion in the minibuffer. For instance, -you can also type `gc[TAB]', and `send-pr' attempts to complete the -entry for you. Typing `g[TAB]' may not have the same effect if several -possible entries begin with `g'. In that case `send-pr' cannot -complete the entry because it cannot determine whether you mean `gcc' -or, for example, `gdb', if both of those are possible categories. -`send-pr' continues to prompt you for a valid entry until you enter one. - - `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, `send-pr' responds -with `[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. - - `send-pr' prompts you for the following fields: - - >Category: - >Confidential: (*default*: no) - >Severity: (*default*: serious) - >Priority: (*default*: medium) - >Class: (*default*: sw-bug) - >Release: - >Synopsis: (*this value is copied to `Subject:'*) - -After you complete these fields, `send-pr' places the cursor in the -`>Description:' field and displays the message - - To send the problem report use: C-c C-c - -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. *Note An Example::, for a sample Problem Report. - - `send-pr' provides a few key bindings to make moving around in a -template buffer more simple: - -`C-c C-f' -`M-x change-field' - Changes the field under the cursor. `edit-pr' prompts you for a - new value. - -`M-C-b' -`M-x gnats-backward-field' - Moves the cursor to the beginning of the value of the current - field. - -`M-C-f' -`M-x gnats-forward-field' - Moves the cursor to the end of the value of the current field. - -`M-p' -`M-x gnats-previous-field' - Moves the cursor back one field to the beginning of the value of - the previous field. - -`M-n' -`M-x gnats-next-field' - Moves the cursor forward one field to the beginning of the value - of the next field. - - `send-pr' takes over again when you type `C-c C-c' to send the -message. `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 *Note Introduction: -(emacs)Introduction. - - ---------- Footnotes ---------- - - (1) If typing `M-x send-pr' doesn't work, see your system -administrator for help loading `send-pr' into Emacs. - - -File: send-pr.info, Node: send-pr from the shell, Next: Helpful hints, Prev: send-pr in Emacs, Up: Invoking send-pr - -Invoking `send-pr' from the shell -================================= - - send-pr [ SITE ] - [ -f PROBLEM-REPORT | --file PROBLEM-REPORT ] - [ -t MAIL-ADDRESS | --to MAIL-ADDRESS ] - [ --request-id ] - [ -L | --list ] [ -P | --print ] - [ -V | --version] [ -h | --help ] - - 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 -SITE is usually the site which you received `send-pr' from, or your -local site if you use GNATS locally. (*Note Setting a default SITE: -default site.) - - Invoking `send-pr' with no options calls the editor named in your -environment variable `EDITOR' on a default PR template. If the -environment variable `PR_FORM' is set, its value is used as a file name -which contains a valid template. If `PR_FORM' points to a missing or -unreadable file, or if the file is empty, `send-pr' generates an error -message and opens the editor on a default template. - -`-f PROBLEM-REPORT' -`--file PROBLEM-REPORT' - Specifies a file, PROBLEM-REPORT, where a completed Problem Report - already exists. `send-pr' sends the contents of the file without - invoking an editor. If PROBLEM-REPORT is `-', `send-pr' reads - from standard input. - -`-t MAIL-ADDRESS' -`--to MAIL-ADDRESS' - Sends the PR to MAIL-ADDRESS. The default is preset when `send-pr' - is configured. *This option is not recommended*; instead, use the - argument SITE on the command line. - -`--request-id' - Sends a request for a `>Submitter-Id:' to the Support Site. - -`-L' -`--list' - Prints the list of valid `>Category:' values on standard output. - No mail is sent. - -`-P' -`--print' - Displays the PR template. If the variable `PR_FORM' is set in your - environment, the file it specifies is printed. If `PR_FORM' is not - set, `send-pr' prints the standard blank form. If the file - specified by `PR_FORM' doesn't exist, `send-pr' displays an error - message. No mail is sent. - -`-V' -`--version' - Displays the `send-pr' version number and a usage summary. No mail - is sent. - -`-h' -`--help' - Displays a usage summary for `send-pr'. No mail is sent. - - -File: send-pr.info, Node: Helpful hints, Prev: send-pr from the shell, Up: Invoking send-pr - -Helpful hints -============= - - There is no orthodox standard for submitting effective bug reports, -though you might do well to consult the section on submitting bugs for -GNU `gcc' in *Note Reporting Bugs: (gcc)Bugs, 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. - * Include anything *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). - - * 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...") but be sure to include anything relevant. - - * Richard Stallman writes, "The fundamental principle of reporting - bugs usefully is this: *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.). - - * Submit only *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. - - * 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. - - * 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. - - -File: send-pr.info, Node: An Example, Next: Installing send-pr, Prev: Invoking send-pr, Up: Top - -An Example -********** - - Cygnus Support in Mountain View, CA, uses GNATS and `send-pr' -extensively for their support activities. As a support company, Cygnus -finds problem tracking to be a crucial part of everyday business. -Cygnus supports the GNU compiling tools (including GNATS and `send-pr') -over several many platforms - - With each shipment of the Cygnus Support Developer's Kit, customers -receive the latest version of `send-pr', which contains an up-to-date -listing of valid categories (values for the `>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 compiling some of our software using the -GNU C compiler, which Cygnus supports. - - 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. - - Our first step is to call `send-pr'. It really doesn't matter -whether we use `send-pr' from the shell or from within Emacs. Indeed, -if we use Emacs as a primary editor, calling `send-pr' from the shell -is likely to start `send-pr' in an Emacs buffer anyway. So, since our -company, *Imaginary Software, Ltd.*, uses GNU software extensively, -we're pretty familiar with Emacs, so from within Emacs we type - M-x send-pr - -and we're greeted with the following screen: - - 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 <---*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 3.2 - - >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)> - >Fix: - -----Emacs: *send-pr* (send-pr Fill)----All------------------ - >Category: other[] - - 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 `C-c C-c'. (The comments have been truncated). - - SEND-PR: Lines starting with `SEND-PR' will be removed - SEND-PR: automatically as well as all comments (the text - SEND-PR: ... - 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 3.2 - - >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. - *code sample...* - - >Fix: - -----Emacs: *send-pr* (send-pr Fill)----All------------------ - To send the problem report use: C-c C-c - - We type `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: - - From: gnats (GNATS management) - Sender: gnats-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 - -This is our receipt that the bug has been accepted and forwarded to the -responsible party. - -A while later, we get the analysis: - - 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> - -About the same time, we get another message from Cygnus. - - 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> - -The bug has now been analyzed, and Cygnus is working on a solution. - -Sometime later, we get more mail from F.B.: - - 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> - - 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> - -The bug has gone into "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 "feedback" to "closed". - - Following is a list of valid `>Category:' entries that are supported -by Cygnus. - -* Menu: - -* Valid Categories:: - - -File: send-pr.info, Node: Valid Categories, Up: An Example - -Valid Categories -================ - -`bfd' - GNU binary file descriptor library. - -`bifrabulator' - This one doesn't actually exist. - -`binutils' - GNU utilities for binary files (`ar', `nm', `size'...). - -`bison' - GNU parser generator. - -`byacc' - Free parser generator. - -`config' - Cygnus Support Software configuration and installation. - -`cvs' - Concurrent Version System. - -`diff' - GNU `diff' program. - -`doc' - Documentation and manuals. - -`emacs' - GNU Emacs editor and related functions. - -`flex' - GNU lexical analyzer. - -`g++' - GNU C++ compiler. - -`gas' - GNU assembler. - -`gcc' - GNU C compiler. - -`gdb' - GNU source code debugger. - -`glob' - The filename globbing functions. - -`gprof' - GNU profiler. - -`grep' - GNU `grep' program. - -`info' - GNU `info' hypertext reader. - -`ispell' - GNU spelling checker. - -`kerberos' - Kerberos authentication system. - -`ld' - GNU linker. - -`libc' - Cygnus Support C Support Library. - -`libg++' - GNU C++ class library. - -`libiberty' - GNU `libiberty' library. - -`libm' - Cygnus Support C Math Library. - -`make' - GNU `make' program. - -`makeinfo' - GNU utility to build Info files from Texinfo documents. - -`mas' - GNU Motorola syntax assembler. - -`newlib' - Cygnus Support C Support and Math Libraries. - -`patch' - GNU bug patch program. - -`gnats' - GNU Problem Report Management System. - -`rcs' - Revision Control System. - -`readline' - GNU `readline' library. - -`send-pr' - GNU Problem Report submitting program. - -`test' - Category to use when testing `send-pr'. - -`texindex' - GNU documentation indexing utility. - -`texinfo' - GNU documentation macros. - -`other' - Anything which is not covered by the above categories. - - -File: send-pr.info, Node: Installing send-pr, Next: Index, Prev: An Example, Up: Top - -Installing `send-pr' on your system -*********************************** - - If you receive `send-pr' as part of a larger software distribution, -it probably gets installed when the full distribution is installed. If -you are using GNATS at your site as well, you must decide where -`send-pr' sends Problem Reports by default; see *Note Setting a default -SITE: default site. - -* Menu: - -* installation:: installing `send-pr' by itself -* default site:: setting a default site - - -File: send-pr.info, Node: installation, Next: default site, Up: Installing send-pr - -Installing `send-pr' by itself -============================== - - Install `send-pr' by following these steps (you may need `root' -access in order to change the `aliases' file and to install `send-pr'): - - * Unpack the distribution into a directory which we refer to as - SRCDIR. - - * Edit the file `Makefile' to reflect local conventions. - Specifically, you should edit the variable `prefix' to alter the - installation location. The default is `/usr/local'. All files are - installed under `prefix' (see below). - - * *Run* - make all install [ info ] [ install-info ] [ clean ] - - The targets mean the following: - - `all' - Builds `send-pr' and `install-sid' - - `install' - Installs the following: - - `install-sid' - `send-pr' - into `PREFIX/bin' - - `send-pr.1' - into `PREFIX/man/man1' - - `SITE' - the list of valid CATEGORIES for the Support Site from - which you received `send-pr', installed as - `PREFIX/lib/gnats/SITE' - - `send-pr.el' - into `PREFIX/lib/emacs/lisp'(1) - - `info (*optional*)' - Builds `send-pr.info' from `send-pr.texi' - (`send-pr.info' is included with this distribution) - - `install-info (*optional*)' - Installs `send-pr.info' into `PREFIX/info' - - `clean (*optional*)' - Removes all intermediary build files that can be rebuilt from - source code - - * Run - - install-sid YOUR-SID - - where YOUR-SID is the identification code you received with - `send-pr'. `send-pr' automatically inserts this value into the - template field `>Submitter-Id:'. If you've downloaded `send-pr' - from the Net, use `net' for this value. - - * Place the following line in `PREFIX/lib/emacs/lisp/default.el', or - instruct your users to place the following line in their `.emacs' - files: - - (autoload 'send-pr "send-pr" "Submit a Problem Report." t) - - * Create a mail alias for the Support Site from which you received - `send-pr', and for every site with which you wish to use `send-pr' - to communicate. Each alias must have a suffix of `-gnats'. The - Support Site(s) will provide the correct addresses where these - aliases should point. For instance, edit your mail aliases file - to contain something like: - - # support sites; for use with send-pr - cygnus-gnats: bugs@cygnus.com # Cygnus Support - bumblebee-gnats: bumblebugs@bumblebee.com # Bumblebee Inc. - mycompany-gnats: bugs@my.company.com (*if you use GNATS locally*) - - `send-pr' automatically searches for these aliases when you type - - send-pr cygnus - send-pr bumblebee - send-pr SITE... - - `send-pr' also uses SITE to determine the categories of problems - accepted by the site in question by looking in - - PREFIX/lib/gnats/SITE - - ---------- Footnotes ---------- - - (1) If your main Emacs lisp repository is in a different directory -from this, substitute that directory for `PREFIX/lib/emacs/lisp'. - - -File: send-pr.info, Node: default site, Prev: installation, Up: Installing send-pr - -Setting a default SITE -====================== - - `send-pr' is capable of sending Problem Reports to any number of -Support Sites, using mail aliases which have `-gnats' appended them. -`send-pr' automatically appends the suffix, so that when you type - - send-pr SITE - -the Problem Report goes to the address noted in the `aliases' file as -`SITE-gnats'. You can do this in the Emacs version of `send-pr' by -invoking the program with - - C-u M-x send-pr - -You are prompted for SITE. - - SITE is also used to error-check the `>Category:' field, as a -precaution against sending mistaken information (and against sending -information to the wrong site). - - You may also simply type - - send-pr - -from the shell (or `M-x send-pr' in Emacs), and the Problem Report you -generate will be sent to the SITE, which is usually the site from which -you received your distribution of `send-pr'. If you use GNATS at your -own organization, the default is usually your local address for -reporting problems. - - To change this, simply edit the file `Makefile' before installing -and change the line - - GNATS_SITE = SITE - -to reflect the site where you wish to send PRs by default. - - -File: send-pr.info, Node: Index, Prev: Installing send-pr, Up: Top - -Index -***** - -* Menu: - -* >Arrival-Date:: Problem Report fields. -* >Audit-Trail:: Problem Report fields. -* >Category:: Problem Report fields. -* >Class:: Problem Report fields. -* >Confidential:: Problem Report fields. -* >Description:: Problem Report fields. -* >Environment:: Problem Report fields. -* >Fix:: Problem Report fields. -* >How-To-Repeat:: Problem Report fields. -* >Number:: Problem Report fields. -* >Organization:: Problem Report fields. -* >Originator:: Problem Report fields. -* >Priority:: Problem Report fields. -* >Release:: Problem Report fields. -* >Responsible:: Problem Report fields. -* >Severity:: Problem Report fields. -* >State:: Problem Report fields. -* >Submitter-Id:: using send-pr. -* >Submitter-Id:: Problem Report fields. -* >Synopsis:: Problem Report fields. -* >Unformatted:: Problem Report fields. -* Arrival-Date field: Problem Report fields. -* Audit-Trail field: Problem Report fields. -* bifrabulator: An Example. -* Category field: Problem Report fields. -* Class field: Problem Report fields. -* Confidential field: Problem Report fields. -* Description field: Problem Report fields. -* Environment field: Problem Report fields. -* Fix field: Problem Report fields. -* From: header: Mail header fields. -* How-To-Repeat field: Problem Report fields. -* Number field: Problem Report fields. -* Organization field: Problem Report fields. -* Originator field: Problem Report fields. -* Priority field: Problem Report fields. -* Release field: Problem Report fields. -* Reply-To: header: Mail header fields. -* Responsible-Changed-<From>-<To>: in >Audit-Trail:: Problem Report fields. -* Responsible-Changed-By: in >Audit-Trail:: Problem Report fields. -* Responsible-Changed-When: in >Audit-Trail:: Problem Report fields. -* Responsible-Changed-Why: in >Audit-Trail:: Problem Report fields. -* Responsible field: Problem Report fields. -* send-pr fields: using send-pr. -* send-pr within Emacs: send-pr in Emacs. -* Severity field: Problem Report fields. -* State-Changed-<From>-<To>: in >Audit-Trail:: Problem Report fields. -* State-Changed-By: in >Audit-Trail:: Problem Report fields. -* State-Changed-When: in >Audit-Trail:: Problem Report fields. -* State-Changed-Why: in >Audit-Trail:: Problem Report fields. -* State field: Problem Report fields. -* Subject: header: Mail header fields. -* Submitter-Id field: Problem Report fields. -* Submitter-Id field: using send-pr. -* Synopsis field: Problem Report fields. -* To: header: Mail header fields. -* Unformatted field: Problem Report fields. -* *analyzed* state: States. -* *change-request* class: Problem Report fields. -* *closed* state: States. -* *critical* severity problems: Problem Report fields. -* *doc-bug* class: Problem Report fields. -* *duplicate* class: Problem Report fields. -* *Enumerated* data types: Fields. -* *feedback* state: States. -* *high* priority problems: Problem Report fields. -* *low* priority problems: Problem Report fields. -* *medium* priority problems: Problem Report fields. -* *MultiText* data types: Fields. -* *non-critical* severity problems: Problem Report fields. -* *open* state: States. -* *serious* severity problems: Problem Report fields. -* *support* class: Problem Report fields. -* *suspended* state: States. -* *sw-bug* class: Problem Report fields. -* *Text* data types: Fields. -* an example: An Example. -* appending PRs: using send-pr. -* appending PRs: Problem Report fields. -* automatic notification: States. -* bad Problem Reports: using send-pr. -* blank PR template: An Example. -* command line options: send-pr from the shell. -* comment section in the PR template: using send-pr. -* completed Problem Report: An Example. -* completion in Emacs: send-pr in Emacs. -* confidentiality in PRs: Problem Report fields. -* Cygnus Support: An Example. -* database similarities: Fields. -* default SITE: default site. -* default PR template: An Example. -* details about send-pr: send-pr in detail. -* editing and sending PRs: Invoking send-pr. -* effective problem reporting: Helpful hints. -* Emacs: send-pr in Emacs. -* errors: using send-pr. -* example of a completed PR: An Example. -* example of a default template: An Example. -* example of a list of valid categories: Valid Categories. -* example of a state change: An Example. -* example PR: An Example. -* example Problem Report: Fields. -* field format: Problem Report fields. -* fields: Fields. -* fields - list: Problem Report fields. -* final state ("closed"): States. -* foreword to send-pr: Top. -* format: Fields. -* generating new PRs: Invoking send-pr. -* GNATS: Top. -* GNATS database fields: Problem Report fields. -* GNATS fields - list: Problem Report fields. -* GNU software support: An Example. -* helpful hints: Helpful hints. -* Imaginary Software, Ltd.: An Example. -* information to submit: Helpful hints. -* initial state ("open"): States. -* installation: Installing send-pr. -* installation procedure: installation. -* interactive interface: send-pr in Emacs. -* Internet standard RFC-822: Mail header fields. -* introduction to send-pr: Top. -* invalid Problem Reports: using send-pr. -* invoking send-pr from Emacs: send-pr in Emacs. -* invoking send-pr from the shell: send-pr from the shell. -* invoking send-pr: Invoking send-pr. -* kinds of helpful information: Helpful hints. -* life-cycle of a Problem Report: States. -* listing valid categories: send-pr from the shell. -* mail header fields: Mail header fields. -* mail header section: using send-pr. -* name completion in Emacs: send-pr in Emacs. -* other mail: using send-pr. -* other mail: Problem Report fields. -* overview to send-pr: Top. -* PR confidentiality: Problem Report fields. -* Problem Report data types: Fields. -* Problem Report format: Fields. -* Problem Report states: States. -* Problem Report template: Fields. -* Problem Reports: send-pr in detail. -* related mail: Problem Report fields. -* related mail: using send-pr. -* Report all the facts!: Helpful hints. -* sample Problem Report: Fields. -* saving related mail: Problem Report fields. -* saving related mail: using send-pr. -* sending PRs: Invoking send-pr. -* setting a default SITE: default site. -* shell invocation: send-pr from the shell. -* state change example: An Example. -* state--"analyzed": States. -* state--"closed": States. -* state--"feedback": States. -* state--"open": States. -* state--"suspended": States. -* states of Problem Reports: States. -* subsequent mail: Problem Report fields. -* subsequent mail: using send-pr. -* template: using send-pr. -* template comment section: using send-pr. -* using send-pr from within Emacs: send-pr in Emacs. -* Using and Porting GNU CC: Helpful hints. -* using send-pr: Invoking send-pr. -* valid categories: Valid Categories. - - - -Tag Table: -Node: Top827 -Node: send-pr in detail2851 -Node: States3690 -Node: Fields5122 -Node: Mail header fields8791 -Node: Problem Report fields9656 -Node: Invoking send-pr17045 -Node: using send-pr17502 -Node: send-pr in Emacs24509 -Node: send-pr from the shell28914 -Node: Helpful hints31261 -Node: An Example34366 -Node: Valid Categories43466 -Node: Installing send-pr45285 -Node: installation45852 -Node: default site49077 -Node: Index50334 - -End Tag Table diff --git a/gnu/usr.bin/send-pr/send-pr.texi b/gnu/usr.bin/send-pr/send-pr.texi deleted file mode 100644 index b9edd9cecbce..000000000000 --- a/gnu/usr.bin/send-pr/send-pr.texi +++ /dev/null @@ -1,657 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename send-pr.info -@settitle Reporting Problems Using send-pr - -@setchapternewpage odd - -@include version.texi -@set SENDPR - -@ifinfo -@format -START-INFO-DIR-ENTRY -* send-pr:: Reporting problems--using send-pr -END-INFO-DIR-ENTRY -@end format -@end ifinfo - -@ifinfo -Copyright @copyright{} 1993 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries a copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). - -@end ignore - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that -the entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions. -@end ifinfo - -@titlepage -@finalout -@title Reporting Problems -@subtitle Using @code{send-pr}, version @value{VERSION} -@subtitle October 1993 -@author Jeffrey M. Osier -@author Cygnus Support -@page - -@vskip 0pt plus 1filll - -Copyright @copyright{} 1993 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that -the entire resulting derived work is distributed under the terms of a -permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions. - -@end titlepage - -@c --------------------------------------------------------------- -@node Top -@top Overview -@cindex foreword to @code{send-pr} -@cindex overview to @code{send-pr} -@cindex introduction to @code{send-pr} - -This manual documents @code{send-pr}, -@ifinfo -version @value{VERSION}, -@end ifinfo -which uses electronic mail to submit support questions and problem -reports to a central Support Site. No body of work is perfect, and -support organizations understand this; @code{send-pr} is designed to -allow users who have problems to submit reports of these problems to -sites responsible for supporting the products in question, in a defined -form which can be read by an electronically managed database. - -@cindex GNATS -@code{send-pr} is part of a suite of programs known collectively as -@sc{gnats}, the @sc{gnu} Problem Report Management System. @sc{gnats} -consists of several programs which, used in concert, formulate and -partially administer a database of @dfn{Problem Reports}, or @dfn{PRs}, -at a central Support Site. A PR goes through several states in its -lifetime; @sc{gnats} tracks the PR and all information associated with it -through each state and finally acts as an archive for PRs which have -been @dfn{closed}. - -Because @code{send-pr} exists as a shell (@file{/bin/sh}) script and as -an Elisp file for use with @sc{gnu} Emacs, it can be used from any -machine on your network which can run a shell script and/or Emacs. - -In general, you can use any editor and mailer to submit valid Problem -Reports, as long as the format required by @sc{gnats} 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 -supplies an address to which further information can be sent; the person -responsible for the category of the problem you report contacts you -directly. - -@menu -* send-pr in detail:: Details about send-pr and GNATS -* Invoking send-pr:: Editing and sending PRs -* An Example:: A working example -* Installing send-pr:: Installing send-pr on your system -* Index:: -@end menu - -@node send-pr in detail -@chapter Details about send-pr and GNATS - -@cindex details about @code{send-pr} -@cindex Problem Reports -A @dfn{Problem Report} is a message that describes a problem you are -having with a body of work. @code{send-pr} organizes this message into -a form which can be understood and automatically processed by @sc{gnats}, -the @sc{gnu} Problem Report Management System. A Problem Report is -organized into @dfn{fields} which contain data describing you, your -organization, and the problem you are announcing (@pxref{Fields,,Problem -Report format}). Problem Reports go through several defined states in -their lifetimes, from @dfn{open} to @dfn{closed} (@pxref{States,,States -of Problem Reports}). - -@menu -* States:: States of Problem Reports -* Fields:: Problem Report format -@end menu - -@include states.texi - -@include fields.texi - -@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 -@cindex generating new PRs - -@include s-usage.texi - -@node An Example -@chapter An Example -@cindex an example -@cindex example PR -@cindex Cygnus Support -@cindex GNU software support - -Cygnus Support in Mountain View, CA, uses @sc{gnats} and @code{send-pr} -extensively for their support activities. As a support company, Cygnus -finds problem tracking to be a crucial part of everyday business. -Cygnus supports the @sc{gnu} compiling tools (including @sc{gnats} and -@code{send-pr}) over several many platforms - -With each shipment of the Cygnus Support Developer's Kit, 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 compiling some of our software using the -@sc{gnu} C compiler, which Cygnus supports. - -Assume that we're getting an error in our @code{bifrabulator} program -wherein the @samp{prestidigitation} routines don't match with the -@samp{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.}, uses @sc{gnu} -software extensively, 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 -@cindex blank PR template -@cindex @code{bifrabulator} -@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)> ->Fix: -@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. - @emph{code sample@dots{}} - ->Fix: -@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: gnats (GNATS management) -Sender: gnats-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. - -@noindent -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:: -@end menu - -@c FIXME - is this list up to date? -@include categ.texi - -@node Installing send-pr -@appendix Installing @code{send-pr} on your system -@cindex installation - -If you receive @code{send-pr} as part of a larger software distribution, -it probably gets installed when the full distribution is installed. If -you are using @sc{gnats} at your site as well, you must decide where -@code{send-pr} sends Problem 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 -@cindex installation procedure - -Install @code{send-pr} by following these steps (you may need -@code{root} access in order to change the @file{aliases} file and to -install @code{send-pr}): - -@itemize @bullet -@item -Unpack the distribution into a directory which we refer to as -@var{srcdir}. - -@item -Edit the file @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 from which you -received @code{send-pr}, installed as -@w{@file{@var{prefix}/lib/gnats/@var{site}}} - -@item send-pr.el -into @w{@file{@var{prefix}/lib/emacs/lisp}}@footnote{If your main Emacs -lisp repository is in a different directory from this, substitute that -directory for @w{@file{@var{prefix}/lib/emacs/lisp}}.} -@end table - -@item info (@emph{optional}) -Builds @file{send-pr.info} from @file{send-pr.texi}@* -@c FIXME - is this still true? -(@file{send-pr.info} is included with this distribution) - -@item install-info (@emph{optional}) -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 -Run - -@smallexample -install-sid @var{your-sid} -@end smallexample - -@noindent -where @var{your-sid} is the identification code you received with -@w{@code{send-pr}}. @code{send-pr} automatically inserts 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 -Place the following line in -@w{@file{@var{prefix}/lib/emacs/lisp/default.el}}, or instruct your -users to place the following line in their @file{.emacs} files: - -@smallexample -(autoload 'send-pr "send-pr" "Submit a Problem Report." t) -@end smallexample - -@item -Create a mail alias for the Support Site from which you received -@code{send-pr}, and for every site with which you wish to use -@code{send-pr} to communicate. Each alias must have a suffix of -@samp{-gnats}. The Support Site(s) will provide the correct addresses -where these aliases should point. For instance, edit your mail aliases -file to contain something like: - -@smallexample -# support sites; for use with send-pr -cygnus-gnats: bugs@@cygnus.com # Cygnus Support -bumblebee-gnats: bumblebugs@@bumblebee.com # Bumblebee Inc. -mycompany-gnats: bugs@@my.company.com (@emph{if you use @sc{gnats} 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 -problems accepted by the site in question by looking in - -@smallexample -@var{prefix}/lib/gnats/@var{site} -@end smallexample - -@end itemize - -@node default site -@section Setting a default @var{site} -@cindex default @var{site} -@cindex setting a default @var{site} - -@code{send-pr} is capable of sending Problem Reports to any number of -Support Sites, using mail aliases which have @samp{-gnats} appended them. -@code{send-pr} automatically appends the suffix, so that when you type - -@smallexample -send-pr @var{site} -@end smallexample - -@noindent -the Problem Report goes to the address noted in the @file{aliases} file -as @w{@samp{@var{site}-gnats}}. You can do this in the Emacs version of -@code{send-pr} by invoking the program with - -@smallexample -C-u M-x send-pr -@end smallexample - -@noindent -You are prompted for @var{site}. - -@var{site} 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 @w{@samp{M-x send-pr}} in Emacs), and the Problem -Report you generate will be sent to the @var{site}, which is usually the -site from which you received your distribution of @w{@code{send-pr}}. -If you use @sc{gnats} at your own organization, the default is usually -your local address for reporting problems. - -To change this, simply edit the file @file{Makefile} before installing -and change the line - -@smallexample -GNATS_SITE = @var{site} -@end smallexample - -@noindent -to reflect the site where you wish to send PRs by default. - -@c --------------------------------------------------------------- -@node Index -@unnumbered Index - -@printindex cp - -@c --------------------------------------------------------------- -@contents -@bye |