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 sense to get the 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.