(Added some common ways to retrieve information and started the bug filing process.)
m (replace weird draft notice with standard one)
|Line 1:||Line 1:|
Revision as of 23:42, 9 October 2008
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.
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.
- Point your browser to the account creation page.
- Request an account using a legitimate email address.
- Check your mail until you receive an account creation confirmation.
- 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.
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
--versionafter the command).
- Operating System
- There are many ways to determine the operating system you are running, but running
uname -sris one way of doing it.
- Two of many ways to determine the architecture of your processor are with
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.