Bug

How to triage bugs in the Debian bug tracking system

September 16, 2011 by Raphaël Hertzog

Triaging bugs is one of the easiest way to start contributing to Debian. I’ll teach you the basics in this article.

1. Prerequisites

All interactions with the Debian Bug Tracking System (BTS) happen through email so you need to have an email account with an address that you’re willing to make public.

All the mail that you send to the BTS will be archived and publicly available through its web-interface. This also means that you should have some spam filters in place because it will inevitably be harvested by spammers. 🙁

To ensure that this email address is consistently used by the various tools that we’re going to use, it’s a good idea to put this email address in the DEBEMAIL environment variable. You can also specify your full name in DEBFULLNAME (in case you don’t want to use the name associated with your Unix account). You usually do this by modifying ~/.bashrc (if you use bash as login shell):

export DEBEMAIL="hertzog@debian.org"
export DEBFULLNAME="Raphaël Hertzog"

You should also install the devscripts package, it provides the bts command that we’re going to use.

2. Find a package or a team with too many bugs

You can literally pick any popular software that’s in Debian, they almost always get more bug reports than the maintainers can handle. Instead of picking a package, you can also select a packaging team and concentrate your efforts on the set of packages managed by the team.

In any case, it’s important to receive the bug traffic for the packages that you’re going to work on. If you went for a specific package, you should subscribe to the package via the Package Tracking System (there’s a subscribe box on the bottom left corner once you selected the source package of interest). If you decided to help a team, there’s usually a dedicated mailing list receiving all bug traffic.

You can browse a list of packages with the most bugs if you have troubles finding a package to work on.

A stack of bug reports to triage

3. Triage bugs!

Bug triaging is all about making sure that bugs are correctly classified so that when a developer looks at the bug list, he can quickly find bugs with all the information required to be able to fix them!

3.1 Adding information to bug

Adding supplementary information is easily done just by sending a mail to XXXX@bugs.debian.org (replace XXXX with the bug number).

But often you want to reply to a message in the bug history, in that case “bts --mbox show XXXX” is for you. It will grab the corresponding mailbox and open a mailer (mutt by default) on it. Now you can directly reply in your favorite mailer.

3.2 Classifying bugs

The Debian BTS uses tags (click the link and read the doc!) to classify bugs. “bts tag XXXX + foo” will add the foo tag (replace the + with a – to remove a tag). If you want to explain why you’re adding a tag, you should instead reply in the bug log as explained above, put control@bugs.debian.org in Bcc (Blind Carbon Copy) and start the body of your message with your tag command:

tag XXXX + foo
thanks

But what tag should you add? When a bug is submitted, you should try to reproduce the bug. If you can reproduce it, then tag the bug “confirmed” (example in #641710). If you can’t, you should request more information (ex: a sample document triggering the bug, a configuration file, the output of some relevant command, etc.) until you can reproduce it or conclude that it was a user mistake. When you request supplementary information due to this, you should tag the bug “unreproducible moreinfo” (example in #526774). “moreinfo” should be later dropped when the requested information are provided, and “unreproducible” should be dropped if those information were enough to actually help reproduce the bug (example in #526774).

During that initial evaluation, it’s also worth differentiating packaging bugs (which are specific to Debian) from upstream bugs (which are relevant also for non-Debian users). The latter should be tagged “upstream” (and forwarded upstream if the bug is reproducible or contains enough information for the upstream developers, example in #635112).

If you saw a (viable) patch in the bug log, the bug should be tagged “patch”. This is usually done by the patch submitter but sometimes it’s forgotten (example in #632460). Take care though to not reinstate the patch tag if it was initially set but then dropped by the package maintainer after a review of the patch.

If the title of the bug report is not descriptive enough, you can change it with a “retitle XXXX new-title” command (example in #170850).

You can also change the severity of the bug report depending on the impact of the problem (with a command “severity XXXX new-severity”, what a surprise!). Request for new features are “wishlist”, most documentation problems are “minor”. On the other side of the scale, you can use “important” for bugs that are very annoying but that should not block a release. “serious”, “grave” and “critical” are used for release critical bugs, check the official definitions of the severities (examples in 502738 or #506498).

3.3 Closing non-bugs and bugs that are already fixed

If your analysis of the bug report is that it’s not really a bug but a user mistake, then you should close it by sending a mail to XXXX-done@bugs.debian.org with some explanations of the user’s mistake so that he can get past his problem (example in #592853).

If the problem was a real bug, but one that is apparently already fixed, you should try to quickly find the version that fixed the bug. If you can’t find it in the changelog (there’s a link to it in the PTS, or you can use /usr/share/doc/package/changelog.Debian.gz), you’ll make the safe assumption that the upstream version you’re currently using is the first one where this is fixed. Then you send a mail to XXXX-done@bugs.debian.org but you start your mail with “Version: version-that-fixed-the-bug” and continue with a small explanation of why you believe the bug to be fixed by this version (example in #122948).

3.4 Reassigning misfiled bug reports

Bug reports are not always filed against the proper package. Users file bugs against applications where they experience the bugs, but the real bug might be in an underlying library or application.

When that happens, you should use the “reassign XXXX correct-package version” command to get it filed against the correct package. The version parameter is optional but should be provided if possible, it should be the oldest version that we know to have the problem (example in #626232).

3.5 Forwarding bugs

Forwarding bugs means opening bug reports in the upstream bug tracker for issues that have been reported in Debian but that applies to the upstream (unmodified) source code. Be sure to include all the relevant information and a link to the corresponding Debian bug.

Depending on the upstream bug tracker, you might have to open an account to be able to file new bug reports.

On the Debian side, you must record that a bug has been forwarded with “bts forwarded XXXX upstream-bug-url”. upstream-bug-url is the URL corresponding to the upstream bug report you created (ex: http://projects.ciarang.com/p/feed2omb/issues/21/ recorded in #609345″).

If the upstream authors fix the bug you reported, you can tag the Debian bug with “fixed-upstream” so that it’s easier to find bugs to close when the next upstream release comes out (example in #637275).

3.6 Updating version information

The Debian BTS uses “version tracking” to know which package versions are affected by a given bug. It’s particularly important to have correct version information for release critical bugs since it might affect the migration of packages to testing.

You can learn more on this topic here: http://wiki.debian.org/HowtoUseBTS.

4. More advice

Colin Watson wrote a constructive rant explaining some mistakes that bug triagers are often doing. While it refers mainly to Ubuntu’s launchpad, the advice apply equally as well to Debian. Check it out to become a better bug triager!

Note that you can refer to this article with this shorter URL: https://raphaelhertzog.com/go/bugtriaging/

Do you want to read more tutorials like this one? Click here to subscribe to my free newsletter, you can opt to receive future articles by email.

How to squash Debian release critical bugs

July 14, 2011 by Raphaël Hertzog

Squashing release critical (RC) bugs is one of the most helpful way to contribute to Debian. Because those are the bugs that we need to get rid of in order to release the next stable version. Let’s see how you can help.

The process is really simple:

Find a RC bug that you can fix
Prepare a fixed package
Send the patch to the BTS
Get your fixed package uploaded

I have already covered points 2 and 3 in a former article: How to prepare patches for Debian packages. So I’m not going to repeat myself in this article, instead I’ll cover how to find a release critical bug to fix and how to get your package uploaded.

Find a RC bug with UDD

The Ultimate Debian Database (UDD) provides a neat interface to query the bug tracking system: http://udd.debian.org/bugs.cgi. The form contains many options to customize the query, we’ll try explain some.

First, at the top, you can decide to list bugs based on whether or not they affect testing/stable/unstable. Indeed, thanks to version tracking the BTS knows if a bug applies to the version of the package present in a given distribution. I suggest you pick a choice that includes “sid” because that’s where you’re going to push your fixed package. If sid is not affected by the bug, you can’t do much about it (except if you want to join the release team and help ensure updates are flowing from unstable to testing).

I usually go for “wheezy and sid” because that filters out packages which are not in testing (and are thus not blocking the next release).

Then you have lots of filters to further reduce the list of bugs. It’s important to reduce the noise as you typically have several hundreds of RC bugs at a given time. I suggest you the following settings for a start, but you’re free to try other combinations depending on what you want to achieve (I’ll give some examples later):

ignore bugs tagged patch (a fix is already available);
ignore bugs tagged pending (a fix has already been committed to the VCS repository);
ignore bugs newer than 7 days (that’s the time we should leave for the maintainer to take care of the bug by himself);

I usually sort the results by source package so that I immediately see if several RC bugs are affecting the source package. And I might add “popularity contest” information to get a feel of whether the package is widely used or not.

You can see the results of the suggested query here.

Other interesting queries:

List of RC bugs blocking the migration of their package (i.e. affecting unstable but not testing, with different version in both distributions).
List of RC bugs on packages that you can adopt (i.e. bugs affecting any distribution but on orphaned packages, sorted by decreasing popularity).

Find a RC bug with rc-alert

The downside of the above method is that you get bugs on packages that you don’t know at all and that you might not care about. Some of them might even be better removed instead of fixed.

With the rc-alert command (provided by the devscripts package), you will get a list of RC bugs on packages that are installed on your computer. It should be much more restrictive. And you have command line options to further filter the list just like with the UDD form. Bonus feature: you can also filter by debtags allowing you to restrict the bugs to packages which are implemented in programming languages that you know.

$ rc-alert --include-dists TU --exclude-tags P+ --debtags implemented-in::perl,implemented-in::python
Package: gwibber
Bug:     608724
Title:   gwibber bypasses certificate checking when providing the login/password for OAuth
Flags:   [     S  ] (security)
Dists:   [STU] (stable, testing, unstable)
Debtags: implemented-in::python, interface::x11, role::program, uitoolkit::gtk, works-with::im, x11::application
[...]

Get your fixed package uploaded

Usually sending the patch to the BTS is more than enough. The maintainer or another Debian developer will pick it up at some point. But if you’re interested in becoming a Debian maintainer/developer, it might be worth to push your changes more quickly and get credited by a proper upload with your name.

Instead of just preparing a patch, you should also prepare a fixed package following the rules of a Non-Maintainer Upload. Put this package somewhere online (for example on mentors.debian.net).

When you send your patch to the BTS, include the link to the updated package and express your wish to get this update sponsored. If you haven’t heard anything from the maintainer after 2-3 days, try to find a sponsor on debian-mentors@lists.debian.org. NMUs are easier to review than completely new packages and many Debian developers like to kill RC bugs, so there’s a good chance that you’ll find someone.

Now happy RC bug-squashing! And if you really enjoy it, you can subscribe to debian-bugs-rc (~3000 mails per month)… 🙂

If you want to read more articles like this one, click here to subscribe to my free newsletter. You can also follow me on Identi.ca, Twitter and Facebook.

7 tips to file useful Debian bug reports and get your problem solved

July 11, 2011 by Raphaël Hertzog

Filing bug reports is the most common way for users to contribute. Even if it’s not too difficult, I’ll give you some advice to improve the quality of your reports. After all, when you go out of your way to report a bug, it is in the hope to see it fixed… so let’s see how we can make this more likely.

1. Try to reproduce the bug

If you can’t reproduce the bug, it’s next to impossible to find the root cause and thus to fix it. In that case, I would suggest you to wait until you experienced the bug multiple times. Maybe you’ll be able to find something that triggers it (or that makes it more likely to encounter it). If the application has a debug/verbose mode, it might be a good idea to enable it until you experience the bug a second time. The generated log might be helpful for the developer to understand what happens exactly.

So don’t file bug reports straight away unless you can reproduce it. The exception to the rule is when the application gives some useful information like a core-dump, a back-trace or an error message.

Obviously if the bug happens during an upgrade, it’s difficult to reproduce it (unless you have multiple computers) but you should still report it. Be sure to include all the relevant information (versions of packages before and after the upgrade, logs of the upgrade, etc.).

2. Do your best to identify the faulty package

When you report a bug to Debian, you must assign it to a package. While there are pseudo-packages useful for problems which are not directly attributable to a real package, in most of the cases you should report a bug against the specific package that seems to be the cause of the problem you encountered.

In turn this often requires you to attribute the problem to a file (for example the executable of the application that triggers the bug). Once you have a filename you can use dpkg -S to identify the corresponding package.

$ dpkg -S /usr/bin/hamster-time-tracker
hamster-applet: /usr/bin/hamster-time-tracker

Note that reportbug accepts a filename as parameter and will do the above conversion for you.

If you only know the name of the application (but not the filename of the associated executable), you can use dpkg -S with a pattern to let it return all possible matches:

$ dpkg -S hamster
hamster-applet: /usr/share/applications/hamster-applet.desktop
hamster-applet: /usr/share/gnome/help/hamster-applet/es/statistics.page
[…]
hamster-applet: /usr/bin/hamster-time-tracker
[…]

Or you can also verify in the list of installed packages:

$ dpkg -l "*hamster*"
Desired=Unknown/Install/Remove/Purge/Hold
| Status=Not/Inst/Conf-files/Unpacked/halF-conf/Half-inst/trig-aWait/Trig-pend
|/ Err?=(none)/Reinst-required (Status,Err: uppercase=bad)
||/ Name            Version         Description
+++-===============-===============-==============================================
ii  hamster-applet  2.32.1-1        time tracking applet for GNOME

3. Verify that the bug is not already reported and/or fixed

If there’s a newer version of the software available, it’s a good idea to try to reproduce the problem with this version too. Because the developers tend to care only about the latest version, they will want to reproduce it with this version, and they will be annoyed if the problem that you reported is already fixed. That’s why bug reports of users of testing/unstable tend to be more useful than bug reports of stable users.

In any case, you want to verify that the bug has not yet been reported: filing a duplicate bug is useless and only generates more work for the developers to merge both bugs together. On the opposite, it’s highly appreciated to add supplementary information to an existing bug report, even a simple confirmation that the bug still exists on a newer version is useful.

Note that reportbug will automatically show you the list of open bugs before allowing you to submit a new one.

4. Use reportbug

While the Debian bug tracking system allows anyone to submit a new bug with a simple mail, you should really use a dedicated program like reportbug (or reportbug-ng) because it will automatically include lots of useful information in the generated report (version of dependencies, current architecture, etc.) and will assist you in all the steps.

5. Describe the problem so that the developer can reproduce it

Ideally your report should include everything required so that the developer can reproduce the problem on his system. If a given document triggers the bug, attach it.

Describe the steps required to reproduce the bug in great details just like you would explain it to your grand-ma. Explain how you expected the program to react and what happened instead.

You can learn much more on how to draft a good bug report in this article: How to report bugs effectively. It’s a bit long but well worth it if you intend to report bugs and thus interact with developers.

6. Be kind and willing to help

When you draft a bug report, keep in mind that you’re writing to a volunteer free software developer and not to a customer service. You should be respectful and follow the usual rules of courtesy. Developers’ attention is scarce and should not be wasted.

Be willing to help, if the developer starts investigating your problem, he might need your help to get supplementary information (in particular if he can’t reproduce it) and you should be ready to provide it. Thus it’s important to keep whatever you need to reproduce the problem.

In some cases, the Debian maintainer might be overworked and you can offer your help to forward the bug to the upstream bug tracker, it’s always appreciated. If you’re reasonably confident that the problem is not Debian-specific, you can do it straight away and set the forwarded field to the URL of the upstream bug report (for example with bts forwarded <bug> <url>).

7. Use the correct severity

The Debian bug tracking system lets you set the initial severity of the bug report (in decreasing severity: critical, grave, serious, important, normal, minor, wishlist). Pick the correct severity according to the official definitions but don’t misread them.

In particular, don’t over-inflate the severity: for instance if you lost some data due to a misuse of the software, it’s not “critical” (i.e. “rm -rf *” doesn’t warrant a critical bug against rm). If you use only a tiny part of a software, and that part doesn’t work, the package might be unusable for you but it’s not unusable for everybody, so it doesn’t warrant the “grave” severity. The “important” severity is often a good choice in those cases.

Do not under-estimate the severity either, if a problem is important enough that it must be fixed before the next stable release (for example a regression compared to the previous release), pick a release-critical severity (i.e. at least “serious”). The maintainer and the release manager can always lower the severity if they do not agree with your initial judgment.

And now, happy bug-reporting! You can refer to this article with this shorter URL: https://raphaelhertzog.com/go/bugreporting/

Follow me on Identi.ca, Twitter and Facebook. Or subscribe to this blog by RSS or by email.