The merging process involves looking at the changes to both the Debian and Ubuntu source packages and determining what has changed and which changes are Ubuntu-specific. Let us now look at an example, a popular CD creation program called xcdroast.

To start, make a folder to hold our project, then navigate there:

mkdir ~/xcdroast
cd ~/xcdroast

Now download all of the source packages involved into this directory:

By looking at the Ubuntu changelog you should be able to see which differences to expect between the Ubuntu package and the Debian package from which it was derived. For xcdroast, the Ubuntu changelog can be found at changelogs.ubuntu.com. It says that a .desktop file was fixed and properly installed to close a bug reported in Malone.

Now inspect the actual changes in the source packages:

debdiff xcdroast_0.98+0alpha15-1.1.dsc xcdroast_0.98+0alpha15-1.1ubuntu1.dsc | \
	ubuntu.debdiff | less ubuntu.debdiff

The lines that start with - have been removed from the Debian package, and those that start with + have been added to the Ubuntu package.

The following is what we see:

Now we know how the Ubuntu source was changed. Now we need to see what has changed in the Debian sources.

debdiff xcdroast_0.98+0alpha15-1.1.dsc xcdroast_0.98+0alpha15-3.dsc > debian.debdiff
less debian.debdiff

There is a lot more in this debdiff than in the last one. One way we can get a better idea of what has changed is to see what files were changed in the debdiff:

grep diff debian.debdiff

This indicates that debian/postinst, debian/rules, debian/changelog, debian/doc-base.manual, debian/control, and debian/menu were changed in the new Debian version.

Thus we can see that we need to check debian/rules to see if the Ubuntu changes were made. We can also see that debian/dirs was not changed from the old Debian version. Let us now look at the files. We can unpack the source package by using dpkg-source:

dpkg-source -x xcdroast_0.98+0alpha15-3.dsc

This will decompress the xcdroast_0.98+0alpha15.orig.tar.gz file, create a xcdroast-0.98+0alpha15 directory, and apply the changes found in xcdroast_0.98+0alpha15-3.diff.gz.

Now navigate to the debian directory:

cd xcdroast-0.98+0alpha15/debian

One can see in rules that changes made by Ubuntu were not applied to the new Debian version. This means that:

cp debian/xcdroast.xpm `pwd`/debian/$(PACKAGE)/usr/share/pixmaps

...should be changed to:

#cp debian/xcdroast.xpm `pwd`/debian/$(PACKAGE)/usr/share/pixmaps

#install desktop and icon
install -D -m 644 $(CURDIR)/debian/xcdroast.desktop \
	$(CURDIR)/debian/xcdroast/usr/share/applications/xcdroast.desktop
install -D -m 644 $(CURDIR)/debian/xcdroast.xpm \
	$(CURDIR)/debian/xcdroast/usr/share/pixmaps/xcdroast.xpm

Now in dirs, the following line needs to be added for the .desktop file to be installed:

usr/share/applications

Now we need the actual .desktop file (saved as debian/xcdroast.desktop). From the ubuntu.debdiff (or the Ubuntu source package), we see that it is:

[Desktop Entry]
Encoding=UTF-8
Name=X-CD-Roast
Comment=Create a CD
Exec=xcdroast
Icon=xcdroast.xpm
Type=Application
Categories=Application;AudioVideo;

The last change that needs to be made is in changelog. Not only do we need to add what we have just done (merge with Debian), but we should also add in the previous Ubuntu changelog entries. To do this, run dch -i -D dapper and put something to the effect of:

xcdroast (0.98+0alpha15-3ubuntu1) dapper; urgency=low

  * Resynchronise with Debian.

Make sure to change the version number to the correct Ubuntu version. Also add:

xcdroast (0.98+0alpha15-1.1ubuntu1) breezy; urgency=low

  * Fix and install existing .desktop file. (Closes Malone #2698)
				
  -- Captain Packager <[email protected]>  Sat,  1 Oct 2005 19:39:04 -0400

between the 0.98+0alpha15-1.1 and 0.98+0alpha15-2 log entries.

Now you can build and test the new source packages. There are different ways to do this, but one example is:

cd ..
debuild -S
cd ..
sudo pbuilder build xcdroast_0.98+0alpha15-3ubuntu1.dsc

This will recreate the source package, sign it with your default GPG key, and build the package in a pbuilder environment to make sure it builds correctly. Make sure to always test your packages before submitting patches. The last step is to make a debdiff that can be attached to an existing bug report or given to the MOTUs in the #ubuntu-motu IRC channel. To do this, we get the difference between the Debian unstable source package and the new Ubuntu version:

debdiff xcdroast_0.98+0alpha15-3.dsc xcdroast_0.98+0alpha15-3ubuntu1.dsc > \
	xcdroast_0.98+0alpha15-3ubuntu1.debdiff