# Bug Report Tool

## Introduction

&application; is a tool which will guide you through making a bug report as painlessly as possible. You can alter things at any stage, and then either send, save, or abandon the resulting report. This document describes version &appversion; of &application;.

&application; can be started a number of ways:

- Choose Programming Bug Report Tool from the Applications menu.

- Run `bug-buddy` at the prompt in a terminal such as gnome-terminal, or from the Run Application dialog.

- If you are using the Nautilus file manager, you can double-click on a core file to start &application;.

- When a GNOME program experiences a bad crash, a crash dialog box is displayed. If &application; is present on the system, then one of the options will be Inform Developers. This button will launch &application;.

&application; is a structured program. At any stage you can continue forward or head backwards to correct earlier details. The goal is to collect all the information which a developer will need to reproduce the same problem and fix it. Some of the information generated by &application; may be unfamiliar to you, but don't delete it. It will be useful to the developers.

## Welcome to &application;

&application; opens with a welcome message and five buttons at the bottom of the screen.

- The Help button loads this document to the help section that is most relevant to the screen you are currently viewing in &application;.

- The About button gives information about &app;'s version and copyright holders.

- The Cancel button will cancel the bug report and exit &application;. You can cancel the report at any time before sending or saving the report, and no information will be sent.

- The Back button will bring up the previous screen so you can change the information that you provided earlier in the report.

- The Forward button will bring up the next screen to continue your bug report. When &application; has collected all the information it needs, the Forward button will change to Save or Send Report, depending on what you have chosen to do with the report.

When you start &application;, you will be asked to select what kind of report to file. The following options are available:

The application does not function correctly

- Select this option if the application produced incorrect results or otherwise behaved differently than you expected.

The documentation is wrong

- Select this option if the documentation does not describe the actual behavior of the application, or if the documentation is incomplete

The translation is wrong

- Select this option if you are using the application in a language other than the application's native language, and the translations in the application are incorrect. Also select this option if translated documentation is incorrect.

Request a missing feature

- Select this option to request the developers to add a feature to the application.

Debug a crashed or running application

- Select this option to report an application crash. Note that if you start &application; from a crash dialog box, then this will be selected automatically, and you will not see the first screen of options.

## Reporting a Crash

If you are reporting a crash, &application; will show the available debugging options. This allows you to perform back traces on a crashed application or to include the core file created when the application crashed. &application; will add the back trace or core file to the bug report automatically.

If &application; was started from a crash dialog box, then the back trace for the application will automatically be included. The debugging information is hidden when &application; is started from a crash dialog box. You can click on the Show Debugging Options button to show the them.

&application; has three options when reporting a crash:

Debug nothing

- This is the default option. If you did not start &application; following a crash and do not have a core file to debug, select this option.

Debug core file

- Select this if you have a core file which you know was created as a result of the bug you are reporting. After selecting this option, you can click on the Browse button to locate the core file on your system. If you started &application; by double-clicking on a core file in the file manager, this option will be automatically selected.

  Core files contain a dump of all the data in memory for the crashed application. If you were using the application to view or edit sensitive information, or if the application had requested or stored your password, do not attach the core file.

Debug crashed application

- If &application; was started from a crash dialog box, this option will be automatically selected. If this option is selected, &application; will prompt you for a binary file and a process ID. If &application; was started from a crash dialog box, these two fields should be filled out automatically. Otherwise, you will need to enter the information manually.

  Binary file

- This is the name of the application as you would type it at a command prompt. For example, if you are reporting a crash in the Nautilus file manager, you would enter `nautilus`.

Process ID

- This is the process ID, or PID, of the running application. The System Monitor displays the process ID of every running application. You can start the System Monitor by selecting System Tools System Monitor from the Applications menu.

This screen contains a text area where debugging options are displayed. You can click on the Copy button to copy the contents of the text area to the clipboard. You can also click on the Save to save the contents of the text area to a file.

## Selecting a Product

The product selection page provides a list of products from which you can select. You can choose to view the listing by product or by application. To view by the products as stored in the bugs database, select the Show Products radio button. To view by applications as they appear on your system, select the Show Applications radio button.

### Updating the Product Listing

&application; maintains a local list of products for bug reports. Each time &application; starts, it checks this list of products against checksums on the bug database servers. If the checksums do not match, &application; will offer to update the product listing.

To get the most recent list of products and components, you should select Update. You may, however, choose not to update the product listing at this time, and you will be asked to do so again the next time you run &application;

## Selecting a Component

After selecting the product, you can select the component, version, and severity of the problem you are reporting.

Each product will have one or more components associated with it. For instance, the Epiphany web browser has the `Printing` component for problems related to printing web pages, the `Bookmarks` component for problems related to the bookmarks system, and a number of other components for other types of problems. Some simple applications will only have one component, typically named `general`. Most products will contain a component for documentation problems, typically named `docs`. If you are not sure which component to select for your report, select the `general` component if it exists.

The Version drop-down box allows you to select which version of the application is causing the problem. You can find the version of most applications by selecting Help About in the application's main window. If you are unsure which version you are using, set the version to `unspecified`.

You can also set how severe you believe the problem to be. The Severity drop-down box has the following choices:

blocker

- Select this if the problem blocks development or testing work on the application.

critical

- Select this if the application crashed, or if the problem causes a loss of data.

major

- Select his if the problem is a major loss of functionality; for instance, if a menu item is broken, data output is extremely incorrect, or the application is otherwise difficult or impossible to use.

normal

- Select this if a minor part of the application is nonfunctional or broken.

minor

- Select this if there is a minor loss of functionality, or if an easy workaround for the problem is available.

trivial

- Select this if the problem is cosmetic; for instance, if a word is misspelled or text is misaligned.

enhancement

- Select this if the report is a request for a new feature or new functionality.

## Frequently Reported Bugs

Before submitting your report, &application; will display a list of the most common bugs reported to the GNOME bug tracking system. Since GNOME is being tested by people all over the world, somebody may have already reported the problem you've found. Please take a moment to review the most frequently reported bugs to see if your problem is already reported. If you find your problem on this list, there is no need to report it again.

If your problem is listed, you can click on the bug number to show the full report in your web browser. If you have additional information to add to the report, please use the web page to do so.

## Bug Description

&application; will ask you to provide a summary and description of the bug you are reporting. If at all possible, please make the report in English. Most developers speak English, although not necessarily as their native language. Writing your report in English will ensure that all developers can understand the problem, which makes it more likely that the problem will be fixed.

The Description text area allows you to describe the problem fully. &application; automatically inserts a template into the description with the following headers:

Description of Problem

- Include a short paragraph providing a brief description of the problem you are reporting.

Steps to reproduce the problem

- Include an itemized list of the steps to take to reproduce the problem. Developers cannot fix a problem if they do not know how to reproduce it.

Actual results

- Include a short description of what the application actually does when you execute the above steps.

Expected results

- Include a short description of what you expect the application to do when you execute the above steps.

How often does this happen?

- If the problem does not occur every time you execute the above steps, say how often it occurs. If you can think of any conditions that might have contributed to the problem occurring, let the developers know.

Additional information

- If you have any additional information about the problem, please include that information here. For instance, if the programs gives any error messages, you should include that information.

You do not have to fill in all the fields, or follow the template exactly. However, the above information is what is generally useful to developers in most bug reports.

If you have any suggestions on what caused the problem or how to fix it, you can include that. If not, don't worry. Just explain what happened. If a developer needs more information, they may email you back asking for it.

## Mail Configuration

&application; gives you two options. You can either send the report directly to the bugs database using `sendmail`, or you can save the report to a file and submit it manually.

If you want to send a bug report to bugzilla directly then you need to fill out the Sendmail Settings. &application; will try to guess the values for these settings. If the information is incorrect, fill in the correct settings.

Name

- &application; will set this to your full name as it is registered on your computer. If you want to use a different name, you can change this setting.

Email

- Please enter a valid email address where you can be reached. Developers may wish to request more information to help them solve the problem you report. You will also be notified when the bug has been closed.

Path of sendmail

- &application; uses `sendmail` to send email to the bug tracking system to submit the report. This field specifies the exact location of the `sendmail` command on your system. &application; fills in this field automatically if it detects `sendmail` on your computer. Usually, you will not need to change this setting.

## Confirmation

Once you have finished your report, you can review the report and decide what to do with it. You will probably want to submit it to the bug tracking system, but you can send it elsewhere if you need to do so.

Your options on this screen will depend on what you chose on the previous screen. See mail-config for more information.

### Sending the Report

If you selected Use sendmail directly on the previous screen, you will see the Send report button. &application; will provide To and Cc fields. You can use these fields to add recipients to the bug report email. As in most mail clients, the proper format is a comma-seperated list of email addresses.

Clicking the Send Report button will send your report to the bug tracking system. You will be sent an automated email from the bug tracking system with a link to a web page where you can track the status of the bug.

### Saving the Report

If you selected Just save to a file so I can submit a bug report manually on the previous screen, you will see a Save button. To save the report, enter a filename in the Save in field and click Save. &application; will save the report to the specified file. You can email this report to the bug tracking system or to a developer at a later time.

## Report Summary

The final screen in &application; will provide a summary of what was done with the report. You can click Close to close &application;.

Thank you for taking the time to report your bug. Reporting problems with software helps the developers create better applications for you. By reporting your problems and suggestions to the bug tracking system, you are playing an important role in the development of free software.