Writing a Linux bug report is usually the quickest way to get your problems fixed and, as a bonus, it also helps save every other Linux user from experiencing the same bug you encountered. Here’s how you can discover what’s wrong with Linux and write a bug report to help get it fixed.
Sometimes it seems like discovering what’s wrong with Linux is a full-time job, especially for less advanced Linux users. Hopefully, the following easy steps will help you quickly find the source of your problem:
- Try to figure out how to reproduce the problem. Then try to reproduce the problem in the fewest possible steps.
- If you’re running a graphical program, try starting it on the command line. You need to know the program’s command name, but you can usually figure this out without much work—for example, Firefox’s command name is
firefox.Many programs print some debugging information on the command line, which you can sometimes use to figure out what’s wrong when you reproduce the problem.
- Read the program’s manual to see if there are any debugging options you can set. You can access the manual for most graphical programs by pressing “F1”. For command line programs, access the manual by typing
man program(replace program with the program’s name).
- Use the information you’ve gathered to search Google. Type in any relevant keywords from error messages and debugging output and try to simply describe what goes wrong. Remember to type the program’s name into the Google search.
- If you discover other people are having the same problem, but you also find an easy solution, you probably don’t need to file a bug report.
- If you discover nobody else has the same problem, then you should file a bug report.
Writing A Linux Bug Report
The first step in writing a Linux bug report is to figure out where you’ll submit the bug report. In most cases, the best place to file your bug is in the bug tracking system of your Linux distribution. If the maintainer of your distribution doesn’t think your bug is his or her fault, then they will usually politely tell you where to send your bug report.
To find the bug reporting system for your distribution, search Google for the name of your distribution plus the word “bug”. For example, the top results for “ubuntu bug,” “debian bug,” and “fedora bug” all go to pages that point you to the bug reporting system for that distribution.
When reporting bugs to a distribution, you also need to know which package to report the bug against. Usually the name of the package uses the name of the program, but this isn’t always the case. On Debian and Ubuntu systems, you can use the following steps to figure out the package name:
- Find the program’s command name, for example
- On the command line, run the command
which firefox(replace firefox with your program’s name). The command which will print the program’s full command name—for example:
- Run the following command to find which package provides /usr/bin/firefox (note this command may take awhile to run if you have lots of packages installed):
dpkg -S /usr/bin/firefox(again, make appropriate substitutions). The output of that command up to the first colon will be the package name. For example, on Debian, the output of the above command is, “iceweasel: /usr/bin/firefox”—iceweasel is the package name.
Before you start submitting bugs, you should learn the two golden rules present in every Linux bug reporting system. Follow both of these rules or you risk having developers ignore or yell at you.
Linux Bug Report Golden Rule #1: Check For Duplicates
Before you file a Linux bug report, you must check for duplicate bug reports. You only need to check for duplicates in the system you’re reporting to—for example, if you’re reporting a bug to Ubuntu, you only need to check for duplicates in Ubuntu’s bug tracking system.
To check for duplicate Linux bug reports, go to the bug reporting system you found earlier and search for keywords related to your bug. Use only one or two keywords at a time so you get the most results possible—you never know how other bug reporters will phrase their Linux bug reports.
Open any bug reports that look similar to your bug. If they seem to be describing your bug, you don’t need to report your bug—but you can can subscribe to the bug report to watch as developers fix it and to test their fixes as soon as they become available.
If you don’t see anyone else reporting your bug, you’re safe to report your bug.
Linux Bug Report Golden Rule #2: Details, Details, Details!
Developers absolutely hate it when someone creates the infamous three word bug report: “Firefox isn’t working.” What developers need are details—the more details, the better your chance they’ll fix your bug quickly. Whenever possible, try to attach the following details to your Linux bug report:
- The name of the program
- The smallest set of steps necessary to reproduce the bug on your computer.
- Details about your computer: what version of Linux do you run (run
uname -ain a terminal), what version of the program do you run (check the Help menu), and what type of system do you have (32bit, 64bit, PowerPC Mac, Intel Mac, Netbook, etc…).
- Any debugging output you collected. Warning: be careful about the debugging output—sometimes it may contain personal information like your username or password. It’s ok to redact personal information by replacing it with fake information, but you should tell the developer that you did so.
- If you can’t describe your bug accurately in words, take a screenshot. (There are numerous screenshot apps, but you can also use the Screenshot option in the File menu of GIMP.)
- If a screenshot doesn’t show your bug accurately, take a video of your screen. For this, you need to install and run the program Istanbul. Please try to keep the video short as bug tracking systems don’t have unlimited disk space.
Finally, even if the bug is making you mad, I suggest you always write friendly bug reports—please remember that almost everyone working on Linux is a volunteer and volunteers don’t respond well to angry demands.
Real Sample Of A Linux Bug Report
Find below the text of a bug report I submitted to the Debian bug tracking system. Notice that it describes everything I know about the bug and includes simple steps to reproduce the bug. The developer of the program used the following bug report to fix the problem the very next day after I submitted it.
Package: nvi Version: 1.81.6-3 Severity: important Within nvi, placing the cursor over a number and pressing the # plus #, +, or - should increment or decrement that number, but now it erases everything from the cursor to the end of the line. For example, if I place the cursor on top of the number two in the following line and press ##, 1 2 3 4 5 6 7 8 9 nvi should produce, 1 3 3 4 5 6 7 8 9 but instead it produces: 1 Preventing my user .exrc file from being sourced doesn't affect the problem. Thanks,
You should now have enough information to write an effective Linux bug report that gets your problems fixed.