2.2 Submitting Problem Reports

Use send-pr to submit Problem Reports to the database. send-pr is a shell script which composes a template for submitters to complete.

You can invoke send-pr from a shell prompt, or from within GNU Emacs using ‘M-x send-pr’ (see section Submitting Problem Reports from Emacs.)

2.2.1 Invoking send-pr from the shell

send-pr [ -b | --batch ]
        [ -d database | --database database ]
        [ -f file | --file file ]
        [ -p | --print ] [ --request-id ]
        [ -s severity | --severity severity ]
        [ -V | --version ] [ -h | --help ]

Invoking send-pr with no options assumes that you want to submit to the local GNATS database named default and calls the editor named in your environment variable EDITOR on a PR template for this database.

-b

--batch

Suppresses printing of most of the messages send-pr usually prints while running.

-d database, --database database

Specifies the database to which the PR is to be submitted; if no database is specified, the local database named default is assumed. This option overrides the database specified in the GNATSDB environment variable. database can also be set to a remote database by using the format for GNATSDB described in Environment variables and GNATS tools.

-f problem-report

--file problem-report

Specifies a file, problem-report, where a completed Problem Report or a PR template exists. send-pr verifies that the contents of the file constitute a valid PR and asks you if you want to edit it or send it directly. If the PR text is invalid you will be told what is wrong and be given the option to edit it. If problem-report is ‘-’, send-pr reads from standard input.

-p

--print

Displays the PR template for the specified database, or if the -d or --database options aren’t specified, print the template for the local default database. No PR is submitted.

--request-id

Sends a request for a Submitter-Id to the Support Site.

-s severity

--severity severity

Sets the initial value of the Severity field to severity.

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

2.2.2 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 (see (emacs)Introduction section ‘Introduction’ in GNU Emacs).

Call send-pr with ‘M-x send-pr’.(1) send-pr responds with a preconfigured Problem Report template. The Emacs interface is described in more detail in a separate section, See section The Emacs interface to GNATS.

2.2.3 The Problem Report template

Invoking send-pr presents a PR template with a number of fields already filled in with default values for the database you are submitting to. 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
• Mail Header
• GNATS fields

The Comments section at the top of the template contains basic instructions for completing the Problem Report, as well as a list of valid entries for the Category field. One (and only one) of these values should be placed in the Category field further down in the Problem Report.

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:

The comments lines 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.)

The Mail Header section of the template contains a standard mail header constructed by send-pr. send-pr can be set up to submit PRs by e-mail or by speaking directly to the GNATS server, but since this header is part of the standard format of Problem Reports, send-pr includes it even when it is set up to speak directly to the server.

To: PR submission address
Subject: complete this field
From: your-login@your-site
Reply-To: your-login@your-site
X-send-pr-version: send-pr 4.2.0

send-pr automatically completes all the mail header fields except the Subject line with default values. (See section Problem Report format.)

The GNATS fields below the mail header form the bulk of a GNATS Problem Report.

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. See section Helpful hints, for suggestions as to what kinds of information to include.

The mechanisms send-pr uses to fill in default values is as follows: Your preconfigured Submitter-Id is taken from the local ‘send-pr.conf’ configuration file. send-pr will set the Originator field to the value of the NAME environment variable if it has been set; similarly, Organization will be set to the value of ORGANIZATION. If these variables aren’t set in you environment, send-pr uses the values set in the local ‘send-pr.conf’ configuration file, if that exists. If not, these values are left blank in the template. 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.

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 (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 validates the contents and if it looks OK either submits it directly to the GNATS server or submits it by mail to the address named in the To field in the mail header.

If your PR contains one or more invalid field values, 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 ‘*gnats-send*’; you can edit this file and then submit it with C-c C-c.

2.2.4 Submitting a Problem Report via direct e-mail

In addition to using send-pr, there is another way to submit a problem report. You can simply send an e-mail message to the PR submission e-mail address of the support site (This address should be published by the support site.)

When you send unformatted e-mail to this address, GNATS processes the message as a new problem report, filling in as many fields from defaults as it can:

Synopsis

The Synopsis field is filled in by the Subject header of the e-mail message.

Submitter ID

GNATS will try to derive the Submitter field from the address in the From header of the e-mail.

Description

All of the text in the body of the e-mail message is put into the Description field.

Other fields, such as Category, Version, Severity, etc. are set to default values as defined by the GNATS administrator.

2.2.5 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 (gcc)Bugs section ‘Reporting Bugs’ in 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.

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

This document was generated by Chad Walstrom on March 3, 2015 using texi2html 1.82.