From Fedora Project Wiki

(Created the page with some initial writing. Not even close to done.)
 
(Added some common ways to retrieve information and started the bug filing process.)
Line 39: Line 39:
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.
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.


=== Steps for Reproducing Errors ===
=== Finding Common Information ===


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 the exact steps you took that led you to the error.
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 <code>--version</code> after the command).
; Operating System : There are many ways to determine the operating system you are running, but running <code>uname -sr</code> is one way of doing it.
; Architecture : Two of many ways to determine the architecture of your processor are with <code>uname -p</code> and <code>arch</code>.
 
=== 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. 
 
<!--
### Not sure if I should put an example like this in here or not...
From there, a procedure might sound something like:
 
First, I started the program by clicking on it in the Applications menu in GNOME.  Then, I created a new document, changed the default text color to red, and went clicked the print button on the taskbar.  That's when the program froze.
-->
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.

Revision as of 22:16, 9 October 2008

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.