How to file a bug report

THIS IS A DRAFT ONLY, FOR USE BY DOCUMENTATION WRITERS AND EDITORS.
DO NOT RELY ON IT FOR ANY ADVICE UNTIL THIS NOTICE DISAPPEARS AND THE DOCUMENT IS PUBLISHED AS FINAL.

Documentation Summary:

Purpose: To describe steps for reporting bugs in language comfortable to novices.

Audience: Linux users unfamiliar with bug reporting

Assumptions: The user is running Fedora linux, has access to the internet, and generally understands how to use computer software.

Related Documents:

Lead Writer: User:danielsmw

---

How to File a Bug Report

This page describes a procedure for reporting software bugs to Fedora developers. A bug is generally defined as "an error, flaw, mistake, failure, fault or 'undocumented feature' in a computer program that prevents it from behaving as intended" (Wikipedia). While many organizations have now adopted Bugzilla as their bug tracking system, this page focuses specifically on the use of RedHat's Bugzilla system for Fedora; however, other users may find the information helpful as well.

Creating a Bugzilla Account

Bugzilla an open source bug tracking tool used for managing reports of issues, defects, and features by users. Bugzilla is generally operated across a web interface. To submit a bug using Bugzilla, you must first create a user account.

1. Point your browser to the account creation page.
2. Request an account using a legitimate email address.
3. Check your mail until you receive an account creation confirmation.
4. Follow the link the email to continue account creation. Fill in the requested fields, and sumbit the form.

Note that if you do not act on the email confirmation within three days, it will expire. In this case, you will need to start from the beginning again.

Once you have created an account, you can login with your email address and password.

Gathering Information

Sometimes, the most important information you can research is whether or not the bug has already been reported. When the same bug is reported several times, developers are often weighed down with having to redundantly read all of them. In the Bugzilla system, use the search feature to see if you can find an already-reported version of your bug.

Before reporting a bug, it is important to collect as much relevant information as possible. As you collect this information, make sure you at least have the following:

• The name and version of the buggy software,
• A qualitative description of what you were doing, and what you were trying to do, when the error occurred,
• The operating system you are running, and
• Your computer's architecture.

Alone, however, this information is rarely comprehensive enough for developers to resolve the reported issue. Consider reporting other information such as other running applications, any peripherals (printers, scanners, camera) that the software might have been interacting with, concurrent issues with other software (another program was malfunctioning at the same time), and the time and date at which the error occurred. The more information the developer can see, the more clues he has as to the source of the malfunction.

Finding Common Information

Your bug report will almost always contain the information listed above, although more often than not additional information will be needed. Nonetheless, it is good to know ways to determine commonly needed data about your bug.

Software Version

The version often be found within the Help menu in a graphical program. For a console utility, the program's man page should tell you what flag to use to print out the version (oftentimes, this involves typing --version after the command).

Operating System

There are many ways to determine the operating system you are running, but running uname -sr is one way of doing it.

Architecture

Two of many ways to determine the architecture of your processor are with uname -p and arch.

Reproducing Errors

Oftentimes, the information you send the developer just isn't enough. In order to understand what was going on "under the hood", so to speak, the developer will need to reproduce the error independently. Therefore, be ready to provide the developer with a step-by-step procedure with which he should be able to reproduce the error. If you feel that there the error is only related to the program, then a good place to start might be the initial execution of that program.

While a pixel-by-pixel description of how you clicked on things is probably not necessary, it is important that you describe the method through which you did something. For example, a program may have several different methods of printing a document: a keyboard shortcut, a menu item, or a taskbar button, perhaps. You need to document which method produced the error.

Filling Out a Bug Report

Once you have successfully logged into the Bugzilla system and collected the necessary data, you can proceed with filing the report. Again, remember to make sure your bug hasn't already been filed by somebody else.