[MOTU] Merging a package from Debian
I'm going to start a series of posts where I walk through various things that I do as part of my Ubuntu development work with the MOTU team. I'm currently trying to get myself up to a level where I can apply to the Ubuntu Universe Contributors team, and then at some point in the future for MOTUship.
This article describes the process for merging a package from Debian to the development version of Ubuntu, currently the Intrepid Ibex. If you want to see how I generally go about doing this, follow the jump.
There's a lot of background on what a merge is, and how to go about performing one at this document on the Ubuntu wiki. To some extent I will repeat the same information here, but presenting it as a walkthrough. Essentially a merge is required when a newer version of a Debian package than the one in Ubuntu is released, and the Ubuntu version has local changes that have been made. The process involves checking the Ubuntu changes, and incorporating them into the new Debian package if they are still relevant. I'm going to outline the way I work with a simpleish merge that I recently did, for the package battleball.
Find a package to merge
The first thing to do is to check either DaD or MoM for the lists of packages for which a merge is currently required. I prefer to use DaD as it has convenient links to the Debian PTS and Launchpad pages for all listed packages, as well as a comment field which can be used by people to indicate that they are working on a package, for example.
Once you've found a package to merge, you should ask the uploader of the last Ubuntu version if they mind you working on the merge this time around. They will be able to tell you if there's anything you need to know about the package or if they plan on working on the merge themselves:
<Laney> norsetto: May I merge battleball?
<norsetto> Laney: pls. do
Once the uploader has OKed you continuing on the merge, you may now start to do the actual work.
Paperwork
We (as a non-MOTU) need a Launchpad bug filed for your merge. This is the place where sponsors will look to check your work. Here is the bug I filed for the battleball merge. The title is the most important part - I usually paste the new Debian changelog entries into the bug description for convenience, but this isn't really required as the bug is mainly just for tracking. Set the status to "In Progress" and assign to yourself. You'll also get a bug number when you file the bug. This is needed later in the process.
Performing the merge itself
DaD and MoM both provide a script, grab-merge.sh, to automatically try to perform a merge by combining the changes in Ubuntu and Debian. I prefer not to use this method, however, as often Debian incorporates Ubuntu changes in a different way which can lead to duplications or omissions in the resulting merged package. This is only a personal preference, and I'm sure that many people get by with the scripts just fine.
Download the Debian package from the PTS page and the Ubuntu package from the LP page and unpack these into their own directories. As we're dealing with the same upstream version (only packaging changes in Debian), I'll use Meld, a really cool graphical diff viewer, to do the bulk of the changes.
Red files have changes, green are new and strikethrough are deleted. The next phase is to inspect each changed file to see if it is still required. Throughout this phase it is essential to refer back to the changelogs to see what changes were made in Ubuntu and Debian. We see that the Ubuntu .desktop file change hasn't been implemented in Debian, so carry this change forward. Inspect each file and see if it refers to this change. It turns out that the changes for this are in battleball.desktop and rules. Use Meld to copy the changes over.
In the screenshot above, we can see the changes between the debian/rules file in the Ubuntu version (left) and the Debian version (right). Changes in blue are in the Debian version but not Ubuntu, and don't require you to do anything. Changes in green are in the Ubuntu version but not Debian. These are the ones we need to pay attention to. Figure out why each of these changes is in the old version but not the new. If they are a result of a Ubuntu change that we still need in the new version, then copy them over by clicking the black arrow in the middle. In this case, both changes are to effect the installation of the desktop file, so are copied.
The debian/changelog file should always be merged. Keep the changelog entries from Ubuntu in the correct place order to preserve the history of the package.
Each change that is kept in the Ubuntu version should be forwarded to Debian using the submittodebian tool to send a patch, as long as it is relevant there too. In this case the .desktop file change has already been reported, so we don't need to do anything further. I like to add a bug watch to my merge bugs with the changes that I've reported as part of that merge. That way the person that comes to merge the package next can easily see if the changes have been adopted in Debian or not yet.
Final housekeeping
Once all changes have been accounted for, and copied over if necessary, it's time to perform the housekeeping tasks that keep our upload tidy and compliant with policy. First we need to update the maintainer to be the Ubuntu MOTU team. This is achieved by simply running the update-maintainer program from a shell within the package's directory. Second we need to add a new changelog entry which details what has gone on. In this case the only change that remains from Ubuntu is the adding of a .desktop file. We also need to mention somewhere in this changelog entry the number of the merge bug that we're closing, in the form (LP: #nnn). Using the command dch -i, we will be presented with an editor which has all of the important stuff (version number, timestamp, distro) inserted automatically. The entry that we come up with is:
* Merge from Debian unstable (LP: #239218), remaining changes:
- Add .desktop file
* Modify Maintainer value to match the DebianMaintainerField
specification. (added automatically byupdate-maintainer)
Testing
Now it is crucially important to test the package. Build a source package by executing the debuild -S command from within the package directory. This will spit out a .dsc and .diff.gz file in the parent directory, which you can use to build the package. I'll not go through the setting up of sbuild here, but you should follow these instructions to get it set up for building packages. This (or pbuilder) is the cleanest and most accurate way of test building. Issue the command sbuild -d intrepid-i386 battleball_2.0-17ubuntu1.dsc to do a test build, and watch the output for any errors. Providing the package builds OK on the current development distro (it does), we can move onto testing. Copy the resulting .deb package onto a VM running the development distro and install it, checking for any errors here. There are none, so we move onto testing the application, in particular looking for the Ubuntu fixes that remain in our merge to ensure that they are still present. In this case the .desktop file is working properly and the program appears to function well after using it for a little while, so we are ready to ask for sponsorship.
Generating files for sponsorship
As a final step before uploading, we need to generate two sets of diffs for uploading: between the debian version we based our changes on and the new version, and between the previous Ubuntu version we took the changes from and our new version. The two commands we need are:
debdiff battleball_2.0-17.dsc battleball_2.0-17ubuntu1.dsc > debian-ubuntu.debdiff
debdiff cur/battleball_2.0-16.1ubuntu1.dsc battleball_2.0-17ubuntu1.dsc > ubuntu-ubuntu.debdiff
Check the changes in both of these debdiffs with diffstat to see that they are all intentional, and verify the diffs manually in a text editor to see that all of the changes you need are present, and all are documented in the changelog.
As they are, we can proceed to uploading and asking for sponsorship.
Uploading and requesting sponsorship
This is the last and possiblly simplest part of the process. Visit the bug's page on Launchpad and upload the two debdiffs you just added, checking the patch box for both of them. I like to paste my new changelog entry to give sponsors a clue as to what's going on in the diffs. Then set the status to confirmed and unassign yourself. From the "Subscribe someone else" page, subscribe ubuntu-universe-sponsors (ubuntu-main-sponsors if this were a package in main), and that's it. Someone will review the patch in good time and upload, thanks to Luca Falavigna for doing this for me here :D.