User:Mcepl/Bug reporting HOWTO

= Bug reporting HOWTO =

Introduction
(based on Bug reporting in Ubuntu by Bryce Harrington -- from 2008-01-18).

This is a (hopefully) brief list of ideas how to make your bug reports more relevant and getting things fixed faster.

The issue reproduction
Some of our most frustrating X.org bugs get titled something like, “X crashes randomly after some period of time.” These are next to impossible to investigate, and usually aren’t worth effort to fix unless the additional information is provided which makes them reproducable. The problem is that for the developer the most helpful thing is to be able to reproduce the bug on his own computer. Only then she could be certain that she perfectly understands whole chain of computer operations which led to the issue at hand. She then could accquire any kind of information about the bug she needs (with tools quite often too sophisticated or difficult for the ordinary bug reporter to use), and especially she can then test whether the proposed fix really resolves the problem.

For many bugs (especially crashes) there is not much to be done unless a developer can reproduce the bug on his computer. Although it is theoretically possible to just fire a fix to the dark and try whether it helps on the reporter’s computer, it is usually much more efficient just to wait whether somebody else will hit the bug as well and will be able to provide better details which will help to reconstruct all details necessary to fix the bug. Therefore, if you want your bug to be fixed, you have to help developer to reproduce it on her computer (barring some exceptionally weird hardware, network conditions, etc.). The following points should help you in this.

Choose a good title and provide thorough description of the bug
An ambiguous title, like “X looks wrong” is going to accumulate a lot of (false) me-too’s, which will both distract from getting your issue solved, and give false hope to the me-too’ers who don’t actually have the same issue.

Also, try to imagine yourself in the position of the developer. Description of the bug " doesn’t work" is mostly useless and most likely will be silently ignored (remember, developers are extremely busy with other bugs, so if you want your problem to be fixed, you need to attract their attention to your problem and persuade them that the issue is worthy of their effort).

Red Hat Bugzilla suggests step-by-step description of the reproduction of the problem, and asks for the expected and actual behavior of the computer. Silently stepping over this suggestion, or deleting it altogether (both of which happen quite often), is highly discouraged. Also filling it with non-specific answers (e.g., "everything should work") shows lack of attention and unwillingness to work towards resolving the problem and in the best case for you leads to long discussion with bug triagers about the information you should file in the first place.

Be as specific as possible in all your answers (e.g., instead of the former, write something like "the green button on the bottom of the window should be lightened, but it stays greyed out"). Although in most cases it looks obvious to you what should happen, and you see what did happen so you feel it is obvious what’s the problem, there is serious lack of crystal balls among Fedora developers and we usually don’t know what is going on inside of your computer.

Attach evidence of your problem
This is the most common important thing most bug reporters fail to do. Anything with error messages is good. The more evidence, the better. Remember, there is almost no limit on the size of the attachments in the Red Hat Bugzilla, and no developer gets offended by providing useless (in his opinion) information, but lack of information and willingness to provide more is the most sure sign of the reporter who will be not helpful in troubleshooting the issue.

For X.org related bugs, this means Xorg.0.log, lspci output, and so on. Photographs of the screen are good too (even video could help in some weird driver-related problems). For kernel bugs, it is usually output of dmesg, and for almost all bugs content of  is very interesting. Configuration files of the crucial elements are always helpful ( for X.org bugs), especially pieces which are different from the standard configuration.

Once again, more information better, and there is never too much information provided for the bug.

Many packages (or groups of packages) have specific requirements for the information. See  below  for information required by the individual packages.

If you have a crash or lockup, attach a backtrace
Another extremely important and difficult to obtain piece of information are backtraces (records of what was program doing in the moment of crash). Yes, backtraces can sometimes be a lot of work to get, but honestly it’s rare that action can be taken on a crash bug until we know where in the code the crash is happening; a backtrace (usually) indicates this. More information about how to collect backtrace for particular programs is on [[BacktraceInfo].

Don’t expect Fedora will fix the bug.
(some note about Red Hat employees -- yes, there are many employees working on our packages, but by far not enough for fixing everything).

Fedora has a huge userbase and while we have a lot of good developers, the rate of bug reporting far, far exceeds our bug fixing abilities. Even a perfectly reported bug can often take several days or a week to create a solution for; for a popular Fedora package (xserver let’s say) it wouldn’t be unusual to have a dozen or two new reports come in over that same time period.

So, in many cases, the best outcome you can hope for is that your bug gets reported upstream. If the maintainer of the Fedora claims that your bug isn’t caused by the problems in the packaging and thus that it should be filed in the upstream bug tracking system, don’t consider it as a rejection from his care, but rather as a promotion to the better place, where not only Fedora people could care about your bug, but whole open source community can help you.

Sometimes bugs really are specific to Fedora, and it’s these bugs that Fedora engineers try to prioritize their time for; obviously if the issue is our fault, we need to put priority into fixing it. We’ll also give priority to bugs that are severe and/or widespread, or that look relatively easy to fix. The former is usually out of your hands, but the latter you can do something about:

Make your bug easier to fix
Even if you’ve followed all the above steps, you still may not see progress on your bug, but that’s not the end of the story! If you have time and patience (or are sufficiently driven by the frustrations), there’s several things you can do to help improve your bug’s chances:

a. Vary some parameters Try reproducing it on different hardware, or different OS’s, or different Fedora releases. Try reproducing the issue several different ways.

b. Find dupes Often other people will report the same issue, but maybe in different ways. Also look at upstream bug tracker (e.g., FIXME) or in the bug trackers of other Linux distributions (be aware though of different versions of the same programs in different distributions). Dupe bugs are valuable because the other reporters often have interesting insights. As they say, “Many eyes make bugs shallow.”

c. Seek out patches If you find a fix somewhere -- forums, upstream bug trackers, casual acquaintances, whatever -- these can often turn the bug into very low hanging fruit. The developer can then just doublecheck that the patch won’t cause issues for other people. Even negative findings can provide valuable clues.

d. Be active with your bug Many bugs cannot be reproduced by the developer, so they rely heavily on the reporter to carry out experiments, test patches, and so on. If you don’t think you have the technical skill to do this, say so and ask for pointers or directions. Naive user who want to be told what to do is not the problem, somebody who behaves like a client of the commerical company is.

General troubleshooting techniques
There is a number of little (or not that little) tips which can help you resolve your issue (most of these are based on or in cooperation with The 10 Step Universal Troubleshooting Process ):

1. Make damage control plan -- Before you do anything that could cause damage, determine appropriate precautions. Specifically, whenever you are to touch any configuration file, unless you use something more fancy (like versioning system), just make a copy of the file with different extension (like  would be copied to  ), in order if all your steps fail, you will be at least no worse than before you begin. Check your regular backups!!! You never know, whether during the fighting your issue, you won’t get too wild and make a damage to your data (plus your system is currently not functioning 100% perfectly, and you are not sure what is the problem, right? How sure are you that the current problem may not lead to something bigger which damages your data?).

2. Test the solution -- after you think you found a solution to the problem (be it your own solution, upgrade of the package from Fedora, or something created in the upstream), check that the solution is actual and complete. Try to do what you know broke the system (which is another reason why thorough description of the original problem is so important -- now you need to be very certain that you are not able to reproduce the problem and therefore that the problem was fixed). Be creative and think about alternative ways, how the problem may show up. Try it as long you really cannot create another test, which would check the problem is solved, or unless you find that the problem is actually not solved (or that it represents itself again under slightly different circumstances). Don’t try to persuade yourself that the problem is solved and limit your testing just to fool yourself.

3. Push the solution to Fedora -- if you found solution of your problem yourself, or if it was resolved by the upstream developers, inform the Fedora maintainer about it, and help him to make necessary changes in the Fedora packages.

Xorg & co. bugs
Please attach your X server config file (/etc/X11/xorg.conf) and X server log file (/var/log/Xorg.*.log) to the bug report as individual uncompressed file attachments using the bugzilla file attachment link below.

Could you please also try to run without any /etc/X11/xorg.conf whatsoever and let X11 autodetect your display and video card? Attach to this bug /var/log/Xorg.0.log from this attempt as well, please.

Anaconda
Specific requirements for the bug reporting about Anaconda installer are available at How to debug installation problems.

Virtualization
For installation problems include /root/.virtinst/virt-install.log  (for virt-install) or /root/.virt-manager/virt-manager.log  (for virt-manager).

If using Xen, then include the output of 'xm list --long' and /var/log/xen/{xend,xend-debug}.log

If using KVM/QEMU, then include the /var/log/libvirt/qemu/{GUEST NAME}.log file if any.