apt-get install debian-wizard

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.

How to prepare patches for Debian packages

July 4, 2011 by Raphaël Hertzog

You want to start contributing to Debian and/or Ubuntu, you decided to help a package maintainer and you’re now looking for how to change a source package and how to submit your changes.

1. Retrieve the source package and install build-dependencies

The first step is to retrieve the latest version of the source package and to install the required build-dependencies. I already covered how to do this with apt-get in the article explaining how to rebuild a source package.

If you prefer, you can use dget (from the devscripts package) to directly grab the source package. You can find the URL of the .dsc files in the Package Tracking System for example.

Sometimes apt-get will warn you that the source package is maintained in a VCS repository, like this:

$ apt-get source wordpress
[...]
NOTICE: 'wordpress' packaging is maintained in the 'Git' version control system at:
git://git.debian.org/git/collab-maint/wordpress.git
[...]

In that case, you can use debcheckout to retrieve the VCS repository instead (provided that you have the corresponding VCS installed):

$ debcheckout wordpress
declared git repository at git://git.debian.org/git/collab-maint/wordpress.git
git clone git://git.debian.org/git/collab-maint/wordpress.git wordpress ...
Cloning into wordpress...

Note however that some maintainers use their VCS in a way that’s not really compatible with the explanations that I will give below.

It’s also a good idea to install the package “packaging-dev”. It’s a meta-package depending on the most common tools that are used for Debian packaging work.

2. Do the changes

Execute dch --nmu to record the fact that you’re working on an update prepared by someone who is not the maintainer (NMU means Non Maintainer Upload). This also ensures that if we build the package, we won’t overwrite the original source package that we downloaded, thus making it possible to generate a “diff” between both versions.

2.1. Modify Debian packaging files

Now fire your text editor and do the required changes in the “debian” sub-directory. You will probably run dch -a multiple times to document each subsequent change.

2.2. Modify upstream files

If you have to modify upstream files, the proper way to do it depends on the source package format (“1.0” vs “3.0 (quilt)” vs “3.0 (native)”, see the debian/source/format file) and on the presence or not of a patch system (the what-patch can help you identify it). In this explanation, I’ll assume that the package is using the recommended format: “3.0 (quilt)”. (It also works for “1.0” if quilt is used and if you configured ~/.quiltrc as recommended by /usr/share/doc/quilt/README.source).

First you should ensure that all patches have been applied with quilt push -a. If there’s no patch yet, you want to create the debian/patches directory (with mkdir debian/patches). Note that you should better invoke quilt from the root of the source package (and the examples below assume this).

2.2.1. Import a patch

If the upstream changes are already in a patch file (say /tmp/patch that you downloaded from the upstream VCS repository) you can import that patch like this:

$ quilt import -P fix-foobar.patch /tmp/patch
Importing patch /tmp/patch (stored as fix-foobar.patch)
$ quilt push
Applying patch fix-foobar.patch
[...]
Now at patch fix-foobar.patch

The -P option allows to select the name of the patch file created in debian/patches/. As you see, the new patch file is recorded in debian/patches/series but not applied by default, we’re thus doing it with quilt push.

2.2.1. Create a new patch

If the upstream changes that you want to make are not in a patch yet, you should tell quilt that you’re going to create one:

$ quilt new fix-foobar.patch
Patch fix-foobar.patch is now on top

Then you must record every file that you’re going to modify with a quilt add invocation. quilt then makes a backup of those files so that it can generate the patch later on. If you’re going to modify the files with your text editor you can just do quilt edit file-to-modify, it’s the same than quilt add file-to-modify followed by sensible-editor file-to-modify.

$ quilt edit foobar.c
File foobar.c added to patch fix-foobar.patch

The last step is tell quilt to generate the patch:

$ quilt refresh
Refreshed patch fix-foobar.patch

3. Test your changes

You should build your modified package with “debuild -us -uc”. You can easily install the resulting package with “debi”. Verify that everything works as expected. If not, continue your modifications until you’re satisfied with the result.

4. Generate a patch and mail it

If you followed the instructions, you should have two .dsc files in the parent directory, like this:

$ cd ..
$ ls wordpress_*.dsc
../wordpress_3.0.5+dfsg-1.1.dsc
../wordpress_3.0.5+dfsg-1.dsc

Generating the patch to send to the maintainer is then just a matter of running debdiff:

$ debdiff wordpress_3.0.5+dfsg-1.dsc wordpress_3.0.5+dfsg-1.1.dsc >/tmp/wp-debdiff

You can send the /tmp/wp-debdiff file to the wordpress maintainer. Usually you send it via the bugreport that your update is fixing and you add the “patch” tag to the report.

This can be automated with the nmudiff utility. By default it assumes that you’re using mutt but it can also directly feed the resulting mail to sendmail. The default text that nmudiff proposes assumes that you’re actually performing an NMU and that the result has been uploaded. If that’s not the case, you should edit the text and make it clear that you’re just sending a patch.

If you have been working in a VCS repository, instead of using debdiff you can simply use the diff feature integrated in your VCS (git diff, svn diff, etc.). But note that with a distributed VCS (like git/bzr/mercurial, unlike svn) you should probably have committed all individual changes in separate changesets. And instead of sending a single patch, you’re probably going to send a series of patches (though it might be easier to just upload your branch in a public repository and give the corresponding URL to the maintainer).

Found it useful? Be sure to not miss other packaging tips (or lessons), click here to subscribe to my free newsletter and get new articles by email.

My Debian activities in June 2011

July 3, 2011 by Raphaël Hertzog

This is my monthly summary of my Debian related activities. If you’re among the people who made a donation to support my work (195 €, thanks everybody!), then you can learn how I spent your money. Otherwise it’s just an interesting status update on my various projects.

Dropbox for Debian

This is not free software but Dropbox is very popular and they did only provide an Ubuntu package that did not work on Debian. So I created an official package.

I have been in touch with Dropbox developers and they have been very helpful. They’ll shortly release a signature mechanism (with GPG) so that we can further improve the package by verifying the origin of the downloaded binaries.

SAT Britney

At the start of the month, I continued my work on the britney reimplementation (the software that creates testing out of unstable) but I quickly stalled it because the release managers asked the feedback of Stefano Zacchiroli and Ralf Treinen (who have extensive knowledge on the topic with their research work on Mancoosi) and I did not want to invest further work in case they would identify a major flow… the feedback came only very late this month and while it was somewhat negative, I still think it’s worth pursuing the effort for a bit longer.

Converted ftplib to multiarch

While dpkg still doesn’t support multiarch (no news from Guillem and no visible sign of progress :-(), unstable got all the remaining bits allowing us to convert libraries to multiarch (see the announce). As soon as the required libc6 landed in unstable, I looked into converting the only library package that I maintain. I had no major problem but I still identified 2 issues in Lintian (filed as #630164 and quickly fixed by Niels Thykier).

build-arch / build-indep support

For the 42th time in the last 10 years, the idea of using build-arch/build-indep targets in the rules file has surfaced again. I had already decided some time ago that I would accept a patch implementing a new field Build-Features to enable dpkg-buildpackage to use those targets and this time Bill Allombert completed such a patch so I merged it.

The technical committee also decided that it would take a final decision on this topic (see #629385). Roger Leigh provided useful input by doing an archive-wide rebuild with the various solutions suggested. Given that the majority would like to make the target mandatory at some point in the future, I provided the dpkg patch for my preferred solution. We would use “auto-detection” as a temporary measure until all packages have been converted to have the targets.

The technical committee has not yet taken any decision even though the discussion stalled since the 12th of June. But that’s usual with that body. I’m sure it will be solved during Debconf. 😉

Misc dpkg work

Modified dpkg-source --after-build to automatically unapply patches if they have been applied by dpkg-source --before-build.
Lots of small bug fixes (#628726, #629582, #630996, #631435, #631439, #631547, #632168) and that’s just to keep with the flow of incoming bug reports!
Added 2 supplementary Perl modules to the supported API for the benefit of Lintian.
Spent an evening to track down the possible causes of an long-standing and annoying assertion failure related to triggers.
Updated my branch with improved triggers directives to take into account the feedback of Guillem, and merged it.
While doing this I discovered a design flaw with the usage of “prerm failed-upgrade” and merged a fix.
Discussed integration of dpkg-buildflags with debhelper in #544844 and decided of further improvements for dpkg-buildflags as a result.

Hamster applet update

Hamster-applet is a GNOME application which did not have a 3.0 release, but it had a development release (2.91.x). I checked out whether it was possible to package this version for experimental and have the applet work with the GNOME fallback mode. Apparently not, the code was not yet updated to be compatible with the newer panel.

Instead I uploaded the latest stable version (2.32.1) to unstable. It has some nice improvements in the standalone version (and the name of the executable changed). For usage with GNOME 3, I have created a custom shortcut to start it quickly (with gconf-editor set /apps/metacity/global_keybindings/run_command_1 to “<Mod4>t” and /apps/metacity/keybinding_commands/command_1 to “hamster-time-tracker” because the GNOME 3 control panel does not seem to work to set custom keybindings currently).

Translated my professional website into English

While I’m grateful for all the people who are supporting my work, I’m still far from my goal to have one third of my time funded through donations and sales of products on this blog.

So I decided to also bring more visibility to my company and in particular to its Debian-related service offering. It was only available in French up to now so I translated it and expanded it a bit. My “support page” on this blog now also links to my company’s website.

If your company needs help to create Debian packages, or needs Debian technical support by email, you just found the right partner. 🙂

BTW, I have discounted prices for individuals and non-profits who would like to benefit from my help to create Debian packages.

The Debian Administrator’s Handbook

This is the title of the upcoming translation of my book. The project now has a dedicated website: debian-handbook.info.

You can subscribe to its RSS feed to keep up with the latest news. The full table of contents is online along with a FAQ.

I’m actively looking for partners to help me promote the fundraising once it goes live. If you can reach a large set of readers interested by a good Debian book, get in touch with me to join the affiliate program.

Thanks

See you next month for a new summary of my activities.

Discover 5 free software that you can support with Flattr

July 1, 2011 by Raphaël Hertzog

The Board (Flattr link) is a sort of digital scrapbook. You can quickly paste and mix notes, pictures, videos, audio recording, … all on virtual pages. The result is very nice and it’s a GNOME application.
Knights (Flattr link) is a chess game for KDE. It’s nice to see some KDE applications on Flattr!
Syncany (Flattr link) is dropbox-like service (file synchronization between multiple computers) except that you can choose where to host your data. It’s a recent project but it looks very promising!
JDownloader (Flattr link) is a java application that simpliefies download of files from One-Click-Hosters like Rapidshare.com or Megaupload.com. It offers downloading in multiple parallel streams, captcha recognition, automated file extraction, and much more.
Ball and Paddle (Flattr link) is an extensible ball and paddle game that lets you script the events and attributes of the objects (balls, blocks, powerups, etc.) with GNU Guile, the official GNU extension language. It’s a GNU project: Flattr seems to be popular among GNU authors apparently. 🙂

This article is part of the Flattr FOSS project.