Ubuntu logo

Packaging Guide

5. Tutorial: Fixing a bug in Ubuntu

While the mechanics for fixing a bug are the same for every bug, every problem you look at is likely to be different from another. An example of a concrete problem might help to get an idea what to consider generally.

Note

At the time of writing this article this was not fixed yet. When you are reading the article this might actually be fixed. Take this as an example and try to adapt it to the specific problem you are facing.

5.1. Confirming the problem

Let’s say the package bumprace does not have a homepage in its package description. As a first step you would check if the problem is not solved already. This is easy to check, either take a look at Software Center or run:

apt-cache show bumprace

The output should be similar to this:

Package: bumprace
Priority: optional
Section: universe/games
Installed-Size: 136
Maintainer: Ubuntu Developers <ubuntu-devel-discuss@lists.ubuntu.com>
Original-Maintainer: Christian T. Steigies <cts@debian.org>
Architecture: amd64
Version: 1.5.4-1
Depends: bumprace-data, libc6 (>= 2.4), libsdl-image1.2 (>= 1.2.10),
         libsdl-mixer1.2, libsdl1.2debian (>= 1.2.10-1)
Filename: pool/universe/b/bumprace/bumprace_1.5.4-1_amd64.deb
Size: 38122
MD5sum: 48c943863b4207930d4a2228cedc4a5b
SHA1: 73bad0892be471bbc471c7a99d0b72f0d0a4babc
SHA256: 64ef9a45b75651f57dc76aff5b05dd7069db0c942b479c8ab09494e762ae69fc
Description-en: 1 or 2 players race through a multi-level maze
 In BumpRacer, 1 player or 2 players (team or competitive) choose among 4
 vehicles and race through a multi-level maze. The players must acquire
 bonuses and avoid traps and enemy fire in a race against the clock.
 For more info, see the homepage at http://www.linux-games.com/bumprace/
Description-md5: 3225199d614fba85ba2bc66d5578ff15
Bugs: https://bugs.launchpad.net/ubuntu/+filebug
Origin: Ubuntu

A counter-example would be gedit, which has a homepage set:

$ apt-cache show gedit | grep ^Homepage
Homepage: http://www.gnome.org/projects/gedit/
$

Sometimes you will find that a particular problem you are looking into is already fixed. To avoid wasting efforts and duplicating work it makes sense to first do some detective work.

5.2. Research bug situation

First we should check if a bug for the problem exists in Ubuntu already. Maybe somebody is working on a fix already, or we can contribute to the solution somehow. For Ubuntu we have a quick look at https://bugs.launchpad.net/ubuntu/+source/bumprace and there is no open bug with our problem there.

Note

For Ubuntu the URL https://bugs.launchpad.net/ubuntu/+source/<package> should always take to the bug page of the source package in question.

For Debian, which is the major source for Ubuntu’s packages, we have a look at http://bugs.debian.org/src:bumprace and can’t find a bug report for our problem either.

Note

For Debian the URL http://bugs.debian.org/src:<package> should always take to the bug page of the source package in question.

The problem we are working on is special as it only concerns the packaging-related bits of bumprace. If it was a problem in the source code it would be helpful to also check the Upstream bug tracker. This is unfortunately often different for every package you have a look at, but if you search the web for it, you should in most cases find it pretty easily.

5.3. Offering help

If you found an open bug and it is not assigned to somebody and you are in a position to fix it, you should comment on it with your solution. Be sure to include as much information as you can: Under which circumstances does the bug occur? How did you fix the problem? Did you test your solution?

If no bug report has been filed, you can file a bug for it. What you might want to bear in mind is: Is the issue so small that just asking for somebody to commit it is good enough? Did you manage to only partially fix the issue and you want to at least share your part of it?

It is great if you can offer help and will surely be appreciated.

5.4. Fixing the issue

For this specific example it is enough to search the web for bumprace and find the homepage of it. Be sure it is a live site and not just a software catalogue. http://www.linux-games.com/bumprace/ looks like it is the proper place.

To address the issue in the source package, we first need the source and we can easily get it by running:

bzr branch ubuntu:bumprace

If you read the Debian Directory Overview before, you might remember, that the homepage for a package is specified in the first part of debian/control, the section which starts with Source:.

So what we do next is run:

cd bumprace

and edit debian/control to add Homepage: http://www.linux-games.com/bumprace/. At the end of the first section should be a good place for it. Once you have done this, save the file.

If you now run:

bzr diff

you should see something like this:

=== modified file 'debian/control'
--- debian/control      2012-05-14 23:38:14 +0000
+++ debian/control      2012-09-03 15:45:30 +0000
@@ -12,6 +12,7 @@
                libtool,
                zlib1g-dev
 Standards-Version: 3.9.3
+Homepage: http://www.linux-games.com/bumprace/

 Package: bumprace
 Architecture: any

The diff is pretty simple to understand. The + indicates a line which was added. In our cases it was added just before the second section, starting with Package, which indicates a resulting binary package.

5.5. Documenting the fix

It is important to explain to your fellow developers what exactly you did. If you run:

dch -i

this will start an editor with a boilerplate changelog entry which you just have to fill out. In our case something like debian/control: Added project's homepage. should do. Then save the file. To double-check this worked out, run:

bzr diff debian/changelog

and you will see something like this:

=== modified file 'debian/changelog'
--- debian/changelog    2012-05-14 23:38:14 +0000
+++ debian/changelog    2012-09-03 15:53:52 +0000
@@ -1,3 +1,9 @@
+bumprace (1.5.4-1ubuntu1) UNRELEASED; urgency=low
+
+  * debian/control: Added project's homepage.
+
+ -- Peggy Sue <peggy.sue@example.com>  Mon, 03 Sep 2012 17:53:12 +0200
+
 bumprace (1.5.4-1) unstable; urgency=low

   * new upstream version, sound and music have been removed (closes: #613344)

A few additional considerations:

  • If you have a reference to a Launchpad bug which is fixed by the issue, add (LP: #<bug number>) to the changelog entry line, ie: (LP: #123456).
  • If you want to get your fix included in Debian, for a Debian bug the syntax is (Closes: #<bug number>), ie: (Closes: #123456).
  • If it is a reference to an upstream or Debian bug or a mailing list discussion, mention it as well.
  • Try to wrap your lines at 80 characters.
  • Try to be specific, not an essay, but enough for somebody (who did not deeply look into the issue) to understand.
  • Mention how you fixed the issue and where.

5.6. Testing the fix

To test the fix, you need to have your development environment set up, then to build the package, install it and verify the problem is solved. In our case this would be:

bzr bd -- -S
pbuilder-dist <current Ubuntu release> build ../bumprace_*.dsc
dpkg -I ~/pbuilder/*_result/bumprace_*.deb

In step one we build the source package from the branch, then build it by using pbuilder, then inspect the resulting package to check if the Homepage field was added properly.

Note

In a lot of cases you will have to actually install the package to make sure it works as expected. Our case is a lot easier. If the build succeeded, you will find the binary packages in ~/pbuilder/<release>_result. Install them via sudo dpkg -i <package>.deb or by double-clicking on them in your file manager.

As we verified, the problem is now solved, so the next step is sharing our solution with the world.

5.7. Getting the fix included

It makes to get fix included as Upstream as possible. Doing that you can guarantee that everybody can take the Upstream source as-is and don’t need to have local modifications to fix it.

In our case we established that we have a problem with the packaging, both in Ubuntu and Debian. As Ubuntu is based on Debian, we will send the fix to Debian. Once it is included there, it will be picked up by Ubuntu eventually. The issue in our tutorial is clearly non-critical, so this approach makes sense. If it is important to fix the issue as soon as possible, you will need to send the solution to multiple bug trackers. Provided the issue affects all parties in question.

To submit the patch to Debian, simply run:

submittodebian

This will take you through a series of steps to make sure the bug ends up in the correct place. Be sure to review the diff again to make sure it does not include random changes you made earlier.

Communication is important, so when you add some more description to it to the inclusion request, be friendly, explain it well.

If everything went well you should get a mail from Debian’s bug tracking system with more information. This might sometimes take a few minutes.

Note

If the problem is just in Ubuntu, you might want to consider Seeking Review and Sponsorship to get the fix included.

5.8. Additional considerations

If you find a package and find that there are a couple of trivial things you can fix at the same time, do it. This will speed up review and inclusion.

If there are multiple big things you want to fix, it might be advisable to send individual patches or merge proposals instead. If there are individual bugs filed for the issues already, this makes it even easier.