Howto: File a bug report on Launchpad

Edit: Unfortunately, the images originally included in this post are gone, because of hosting problems in late 2009. My apologies.

Since my new rules require that I do a better job keeping up with the little glitches and quirks I find, it’s probably a good time to show how to file a bug report.

First of all, don’t be intimidated by this. Filing a bug report is as easy as starting a new thread on the forums (and in a way, it is the same thing), and no one is going to get salty with you or tell you “ur doin it rong.” Naturally, there are some courtesies and protocols you should follow, but for the most part common sense and a little patience are your greatest assets.

Almost everything I talk about here is already available in better detail on other sites. For example:

• Reporting Bugs on the Ubuntu wiki. The wiki gets a lot of criticism, even from Ubuntunuts (myself included), but for the most part it’s a good starting point.
• Filing Bug Reports Using Launchpad. John.Michael.Kane‘s long-standing but brief sticky in ABT is a good overview, although to a newcomer it might seem a little sparse.
• How To Test Hardy, File Bugs and Repair Breakage. 23meg lays down the law for Hardy testers, in great detail and with plenty of tips. Most of his advice applies to other releases too, not just Hardy.

Note that a bug report is different from a feature request. What’s the difference? Well, it should be fairly clear: If something is broken and doesn’t work, that’s a bug. On the other hand, if you wish something behaved a certain way or you wish a different idea were in place, that’s a feature request. You’re the best judge of which is which, but as examples … GUI is gone? Bug. Don’t like the wallpaper? Feature request.

(“Okay, so why did you file your complaint about coreutils and the rm -rf default as a bug report and not a feature request?” you ask. Simple: That behavior destroys an installation. In my opinion, a default setting that can cause a system to implode is a bug. You’re free to debate the point, but the deed is done.)

And a feature request is a different animal from a support request. That’s what you post on the forums when something isn’t behaving as you expect it should. If you have a bug, you’ve probably already looked for answers elsewhere, and so I don’t think you need coached on that point. Don’t forget to search the forums, search them with Google, and to also check Launchpad Answers. Look around before filing a bug; you’ll be saving yourself (and some other people) a lot of time.

There are really only three things you need to file a bug report:

1. A Launchpad account. Launchpad is the tracking system Ubuntu and a lot of other projects use to make sure bugs and things are properly followed.
2. A good, complete description of what went wrong. Remember that your ability to list details, supply error messages and explain what happened will go a long way toward seeing your bug squashed. If your English isn’t strong or you know you have difficulty getting your thoughts into words, have someone help.
3. An idea of where the error lies. In other words, you should have an idea of which program is causing the error.

That last one can be the hardest one, especially when something is catastrophically screwed up. What’s going wrong if the entire computer freezes? or if it restarts at random? or just never starts?

It’s hard to say. Use your best judgment and intuition. If you just installed a new version of program X and now your desktop looks like a dirty windscreen after a five-hour cross-country drive, then you can probably guess that the problem was program X. If it’s after a system update and you remember that the kernel was one of the things updated, you might be able to point a finger at the kernel.

Which brings up an interesting point: If your bug is something that originates beyond Ubuntu’s control, it might be called an “upstream” bug. If you’re familiar with English idioms, you’ll understand that calling it an “upstream” issue suggests the problem is best fixed with the people who made the original software.

For example, for the longest time, Leafpad had an issue where search-and-replace left spattered duplicated text elsewhere in the file. Filing a bug with Ubuntu would have been of little use, since the problem was within the code for Leafpad. Occasionally Ubuntu developers will tweak or adjust software so it works properly in Ubuntu, but you can’t expect that for everything.

What that means is that you might have to file a bug report elsewhere — like with the original programmers — to get your bug fixed. If that’s the case, then you’ll be learning a new bug tracking system and filing reports elsewhere. If I can find a bug in an upstream package, I’ll do that too as an example.

That’s enough jibber-jabber. Let’s try one out.

This bug is one I’ve been sitting on for a very long time: the persistent and gobsmacking tty of death that happens on my ancient and esoteric Sotec laptop. This happened in Feisty, in Gutsy and still happens even in Hardy alphas. Why? Because I never reported it, probably!

In any case, here’s what I know:

1. I know my hardware. I know my video card is a Silicon Motion SM712 LynxEM+, and I know Ubuntu should be using the siliconmotion driver to communicate with it. I do know that my xorg.conf file doesn’t usually show that as the driver, and I have to set it manually.
2. I know what happens with the bug. If I switch to a tty screen with CTRL+ALT+F1 or another key, I get nothing — only a black screen. I can switch back to X, but jumping away from X or exiting X completely disrupts the terminal screens, and they never come back. It also happens when X goes into power-saving mode, and turns off the screen. The consoles are still active back there, because I can type commands to reboot or shut down the computer — I just can’t see what’s happening.
3. I’ve also troubleshooted it, as much as I can. I know that different drivers do the same thing, and changing things like the color depth or the resolution has no effect on the bug. I’ve tried subtracting modules from the setup, and It happens regardless of the window manager or desktop environment. If I could, I’d take a screenshot of it, but it’s just a black screen, so there’s little to show.
4. I also know how my system behaves under other distributions. Since the GUI never does this under other versions of Linux, I’m fairly confident this is a bug with Ubuntu only, and not something upstream.

So what’s at fault here? Hard to tell, isn’t it? Luckily, there is some guidance on the wiki — the Find the Right Package page.

This is an important stop on your bug reporting adventure, because some software — like the kernel, or X — need specific information to be properly fixed. And so this is where the courtesy and patience I mentioned earlier come into play: You’ll need a little patience to show the necessary courtesy to get your bug fixed. If you omit something that’s needed to fix your bug, you’ll probably get a terse request for more information. Nobody’s being surly; it’s just that you’ve pointed out an error without giving up some of the info needed for fixing it. In some cultures, that’s kind of rude.

Judging by the Find the Right Package page, I probably have an X bug on my hands. That means I need to file my bug against the xorg package. And this is a good example, because filing bugs for X can be complicated. I don’t get to just jot a note and run off.

Take a look at the needed information for a good xorg bug report. Judging by the descriptions of problem classes (under “What to Include in Bug Reports”), I’m going to guess this is a “General X problem.” So I need to include:

1. Description of problem
2. Paste in output of lspci -nn | grep VGA
3. Attach /etc/X11/xorg.conf
4. Attach /var/log/Xorg.0.log
5. Attach output of lspci -vvnn

That’s not a lot. The only challenge will be getting most of these immediately in the wake of the bug, since I usually can’t see what I’m doing when it happens! 😀 If somebody wants more information (which I don’t anticipate), they’ll ask for something specific at a later time.

Now log in to Launchpad. If you don’t have a Launchpad account, you’ll need one to go any further.

A Launchpad account isn’t much different from a forum account. You’ll need an e-mail address and you’ll have to pick a unique name. It’s probably in your best interest to use valid accounts here, since most of your communication with the developers regarding your bug will be through Launchpad bulletins sent to that e-mail account. So don’t use one you plan to throw away … or one you like to keep private.

(As a side note, it has long been a dream of the Ubuntu overlords to mesh the forums and Launchpad into one account, which means joining the forums would give you a Launchpad page, a wiki page and a free “Hello, my name is” sticker. Okay, maybe not the sticker. In any case, that idea has been kicked around for years, so don’t hold your breath waiting for it to materialize.)

Giving your bug a title is the next step.

Note that in the debugging guide, there’s a section about “Choosing a Good Title.” A good one is short, sweet and accurate. I think I’ll call mine … “[Feisty,Gutsy] Switching to tty yields black screen (SiliconMotion)”. That way, in one fell swoop, I tell the triage team which releases, what driver/hardware and what happens.

(I didn’t include Hardy because my Hardy test system was only partially working. Alpha software sometimes has too many bugs to be practical … when you’re writing a howto. 🙂 )

The next step is important. Nobody like duplicate bugs. There are hundreds of thousands of “bugs” in Ubuntu, but only a portion are unique — the rest are duplicates that were submitted again because someone didn’t take the time to look and see if theirs had been reported.

Scan through the bugs with similar titles, and see if there’s one there that might be yours. If there is, you can open it in a new window and check it over. If nothing there looks like yours, click on “No,” and you’ll get a form to submit your bug. But don’t worry if your bug is later marked as a duplicate; there are so many bugs that it’s almost impossible for you to track down a similar one. There are people who know much better where the bugs are, and how they are arranged and ordered. But still, try to help by not filing one that’s obviously the same.

Since I’m filing this against X, my package is xorg. I included as much of a description as possible, noting the few troubleshooting steps I took. I pasted in the shortened output from lspci, and attached the remaining files on the next page, after the bug has been submitted (I don’t know why there’s no attachment function on the form page; if you find it, tell me where it was).

When it’s all said and done, this is what it looks like.

Easy as pie. Now what happens? Well, for this one, probably not much. I’m guessing that my hardware and configuration are far too unusual to send the Ubuntu superstructure into a bugkilling frenzy.

But you never know. It’s possible that one of the devs or a triager will see that, know of a fix, and will reply. If not, it’ll get forwarded up the chain. But the chore is over, if you thought it was a chore.

And really, this is a bigger chore than most, because it was against such a huge package. If you file a bug report against … oh, I don’t know, Leafpad or something, you’ll have a lot less to deal with. But this was a good first example.

Of course, this isn’t the end. If a dev wants more information, they’ll reply, which should find its way back to you as an e-mail to your launchpad account. If someone else sees your bug and has a comment, that too will be sent to you. So you’re now part of the Ubuntu bug reporting community. I suppose you’ll need that “Hello, my name is …” sticker after all. 🙄

As a final note, I have a couple of suggestions in your bug quests. These are really from my own experience, and not necessarily the gospel.

• Whenever possible, chase bugs in a sterile environment. Try to make your system as close to default as you can, or even from a live environment, which is usually exceptionally clean. Speaking from experience, the more you tweak and twist an installation to make things work, the more likely you are to draw in even more variables, making it more difficult to track down the real problem.
• Try different editions, updates, or releases. Jump to a different distro and see if it’s better. Jump to a related distro and see if it still is a problem.
• Ask for help. It never hurts to ask the general population what could be wrong; you never know. Someone might have encountered the same issue and solved it with as little as a short edit. You should probably still file a bug report, but fix it for yourself first, and add your solution to your report.

Now go out there and make the world a better place! 😀