From Fedora Project Wiki

Revision as of 14:31, 10 October 2008 by Sundaram (talk | contribs)

This page is a draft only
It is still under construction and content may change. Do not rely on the information on this page.

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

Note: You seem to be duplicating http://fedoraproject.org/wiki/BugsAndFeatureRequests - RahulSundaram



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

The common actions pane at bugzilla.redhat.com. Click "Enter a new bug report" to begin.

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.

After logging in at https://bugzilla.redhat.com, you should see a side pane with common actions. Click on "Enter a new bug report".

After starting your bug report, you will be prompted to choose the project your bug is in. If you experience a bug using Fedora Linux, then you should probably click "Fedora" here. The next menu will present options for categories within the project you selected. If you found a bug in some software, you should probably just click "Fedora". Each category has a short caption to help you choose one. If you find an error in the documentation, for example, you may want to click "Fedora Documentation" instead.

If, for some reason, you really just can't decide where your bug belongs, don't give up. Just submit it somewhere, and the developers will reassign it to the appropriate project if necessary.

Once you have selected your bug's category, you will need to fill out the actual report. There are two methods for doing this; you can use the standard form or the guided form. The guided form is recommended for new users.

Either way, make sure you have all the information you collected earlier, and start to fill in the fields.

Guided Form

The guided form provides an easy step-by-step method for filing bugs. By default, however, you will see the standard form. To switch to the guided form, click "Guided" in the second sentence on the page ("You may also use the Guided bug entry page for a easier step by step method. "). The guided form involves three steps.

First, determine if your bug has already been reported. The first step will allow you to search through bugs on record so you can ensure that your bugs is not already registered in Bugzilla.

Next, you need to give detailed information about your bug. Fill in each of the queries:

Component
Choose the name of the software that is giving you trouble. Depending on your bug, this might also be a documentation file or other component of Fedora.
Hardware Platform
This is your architecture that we determined earlier. If, for some reason, you are unsure of your platform, you can probably choose i386; however, make every effort to be sure of your architecture if you can.
URL
This is an optional field, and you can leave it out unless it applies to you.
Summary
Fill in a short, one sentence description of the problem. For example, "Saving file in .tiff format causes program to exit."
Details
This is your long version of the issue. Be as specific as possible. Make sure to give a rational, complete depiction of the problem; saying "The print button is broken" is not sufficient.
Reproducibility
This is a very important field. Does this happen every time you follow some procedure? Does it only happen on Tuesdays? Was it only once?
Steps to Reproduce
As discussed earlier, provide the steps you followed to reach the bug. If the problem cannot be reproduced, say so in "Reproducibility" and give the steps to the best of your memory.
Actual Results
What happened when you reached the bug?
Expected Results
What do you think should have happened?
Additional Information
If there's anything else you feel the developer need to know, you can put it here. This might be an error message from console output, or it might be the model of your camera that was connected when the bug occurred.
Severity
When reporting the severity of the issue, be reasonable. Try to be objective. Remember that, although the error may inconvenience you, it may not actually be a big deal. Each severity level has a caption that should help you decide.
Security
If you have identified a security-compromising problem, it needs to be noted here. These can often be serious issues.
In guided mode, there is no button for creating an attachment. If you have a screenshot, error log, stack trace, or any other important information you want to submit, you'll have to use the "Create a new Attachment" link on the bug after you submit it.

Finally, click submit, and check your email periodically for updates on the problem or clarification questions from developers.

Standard Form

The standard form is less verbose but easier to use if you know what you're doing. Only fields relevant to the average end-user are described here. If you don't understand a field in the form, it's probably okay to leave it blank.

Component
This is where you choose what part of Fedora is giving you trouble. This may be, for example, a software package.
Severity
Select how important you think your bug is. Keep in mind that this is not how important the bug is to you, but how big of an issue it is for Fedora users in general. If a dialog box is showing up a few extra pixels to the right, it isn't a big deal; however, if running a program crashes the system and wipes your hard drive (or something else drastic like this), you should probably select "urgent". Use your common sense in this field.
Platform
This is your architecture, as described earlier. If for some reason you aren't sure of your architecture, chances are that it's i386, but make an effort to find out definitively.
OS
If you're running Fedora, you can choose Linux here. Otherwise, choose appropriately; if you aren't using Fedora, however, make sure there's a good reason for filing a bug under the Bugzilla system for Fedora.
Version
This refers to your OS version. If you are running a pre-release version of Fedora (a beta release, for example), then you should select "rawhide" here.
Summary
Give a short description of the issue ("Saving file in .tiff format causes program to exit.", for example).
Description
This is where you give most of your details. A template should already be provided for you to fill in information. Make sure you give an extended description of the problem, the software version, steps to reproduce the error, and the difference between what should have happened and what actually happened. You can add any other information that you think is important at the end; for example, if the bug involved a peripheral device or a display error, you may want to give the type and model of the device you were using.
Attachment
You can attach a file here if you feel it will help the developer understand you error. Error logs and screenshots are both good choices, but nothing is required.

IRC Channels and Other Social Channels

IRC channels, personal email, and other social channels such as instant messaging are great ways to discuss software issues, but they should not used to formally file a bug.