Ubuntu Wiki

This page might need some cleanup / reorganisation. Don't hesitate !

Merging and Syncing from Debian: Introduction

Until UpstreamVersionFreeze, Debian packages are automatically synced to Ubuntu if Ubuntu has no local changes. If the Ubuntu version has local changes (a -ubuntuX version), the package shows up on [http://merges.ubuntu.com/ (MoM)] and manual action must be taken.

• If all Ubuntu-specific changes can be overridden (because they were integrated into Debian, or because they are no longer necessary), the package can be synced: the Debian package will simply get into Ubuntu.

• If some Ubuntu-specific changes have to be kept, the package has to be merged.

Read also [:MOTU/Packages/Merging: Merging].

Useful tools

• [http://merges.ubuntu.com Merge-o-Matic Index] - Start here

• [http://merges.ubuntu.com/universe.html Merge-o-Matic Universe Index] - Detailed list of outstanding and updated merges for the Ubuntu Universe component. If you did some merging work previously in Dapper, you can take a look here and see if your touched packages need a new merge to the available Debian version.

• [http://merges.ubuntu.com/grab-merge.sh grab-merge] - Simple tool for grabbing Debian and Ubuntu sources for a package for merge processing.

Older, but Still Very Useful Stuff

• [http://tiber.tauware.de/~shermann/motu-tools/ motu-tools], a set of scripts by ReinhardTartler, StephanHermann and others. Read the README.

• MultiDistroTools, a set of scripts to easily work on both Debian and Ubuntu.

Some reasons for divergence between Debian and Ubuntu

See also [http://lists.ubuntu.com/archives/ubuntu-motu/2005-December/000080.html this thread].

During the merging for dapper, we want to try and clean up as many packages as possible, including various things such as getting patches upstream and fixing any mistakes we made in the past.

Build System Changes

During breezy, many people decided to put dpatch on top of a package, and use that as the source code patches.

The decision to do this has been reversed, for three main reasons:

• It is a generally accepted procedure in Debian to leave the maintainer's build system unchanged
• It makes our patch deltas larger, creating more issues later when merging our changes with Debian
• It annoys some Debian maintainers, and we want to try and keep on good terms with them as much as possible.

As such, packages which have integrated dpatch should probably be reversed, see the ["MOTU/HowToPatch"] page for information on how source patches should be applied

If you are not sure, ASK! The IRC channel and Mailing List are there to be used

Please note that if a patch system is in place in the package, the patch system should be used when making changes to the package source (outside the debian/ directory)

Check for obsolete patches, send patches upstream

During breezy, we have applied patches to packages for various things, these include (but are not limited to, feel free to expand this list)

• Desktop Files
  • We also have patches for desktop files, it has been suggested by seb128 that we send .desktop files UPSTREAM TO THE SOURCE! (not Debian), if upstream is unresponsive, try Debian.

Try to drop the need to merge all together

Hopefully, after going through all this, you will be left with no changes to merge. GREAT! This means we could just request the package be synced directly from Debian.

If you still need to merge

Then do so, as appropriate. Don't forget, File patches in the Debian or upstream bug tracking system, IF APPROPRIATE, the above transition list should be a starting guide on whether or not it is suitable. If you are unsure ask someone! People are here to help you

How to work on merges and syncs

The easy way, using MOTU-tools

The easiest way to merge packages is to use the [http://tiber.tauware.de/~shermann/motu-tools/ motu-tools]. You can use [http://bazaar-vcs.org/ Bazaar] to get these tools:

• Install the bzr package

• Type bzr branch http://tiber.tauware.de/~shermann/motu-tools/

You should find a README file in the motu-tools directory. It explains step-by-step how to use motu-tools during the merging process.

General tasks to be done

There are several ways of merging packages. The one described here is merely a suggestion, but contains the mandatory steps.

File a bug

Before you work on one merge, file a bug in [http://launchpad.net/ubuntu/+filebug Launchpad] against the source-package product:

• BUG Title Format: <sourcepackage-name>: merge new debian version

• BUG Description Format: {{{MoM: <url to merged package directory>

MOTU: <your name>}}} The url to the merged package directory has the form of: http://merges.ubuntu.com/<letter>/<source-packagename> (where <letter> is the first letter of the source package name, or lib plus the next letter of the source package name for source packages whose names start with lib).

Subscribe "ubuntu-universe-sponsors" to the bug (find the right assignee via Choose link, don't use the tiber.tauware.de address)

If you are using the MOTU-tools, you can use ./lpbugs.py -n <sourcepackage> to file this bug. Note that lpbugs.py won't assign the bug to ubuntu-universe-sponsors, so you'll need to to it manually either now or when you're done preparing the merge.

Get the files you need

The first thing to do is to get the package sources:

• Fetch the <package>.diff.gz, <package>.orig.tar.gz, and <package>.dsc files from http://merges.ubuntu.com/<letter>/<package>/ and use dpkg-source -x <package>.dsc to extract the source. This source is only a merge suggestion provided by MoM.

• Get the Debian package source:

  • If you have a sid chroot (see DebootstrapChroot), you can use apt-get source <package> in it.

  • If you don't have a chroot, get the <package>.diff.gz, <package>.orig.tar.gz and <package>.dsc for sid from [http://packages.debian.org] and run dpkg-source -x <package>.dsc to extract the source.

  • If you use MultiDistroTools (not yet packaged for Ubuntu), you can use: mdt dist-apt-get sid source <source-packagename>

Get to work

• Check the package_ubuntu.debdiff file to check what has been modified in Ubuntu in previous versions and why.
• Check if the changes made in Ubuntu have been merged in Debian. If it is not the case, try to find out why, and if these patches are still necessary.
• Try to build the Debian package souce in Dapper, preferably using a PBuilder.

If the Ubuntu patches can be dropped, you can use lpbugs to update the bug: ./lpbugs.py -u -b <bugid> -s

Case of a sync

If the patches are not necessary any more and the Debian package source builds, installs and works fine, then it is a [:SyncRequestProcess:sync].

Case of a merge

Update the bug on Malone to tell you're working on the merge. If you're using the MOTU-tools, use ./lpbugs.py -u -b <bugid> -p .

So there are changes to do on the Debian package source? Look closely at the patches and diffs provided by MoM and try to make the minimal change to set the package right. Work directly on the Debian package source.

Once you're done patching the package, don't forget to update debian/changelog. You have several options to do so. An easy one is to use the debian/changelog created by MoM from the packages extracted using the merged source (from the dsc and diff.gz fetched from http://merges.ubuntu.com/):

• Extract the MoM package source using dpkg-source -x mergedpackage.dsc if it's not done yet.

• Copy debian/changelog from this source to the Debian package source.
• Use dch to update the file, or modify it manually. Add as many infos as necessary to make your changes fully understandable. The new package version should be -Xubuntu1, where X is the Debian version on which the merge is done.

After you're done with this, rebuild the package with debuild -S -sa, and check if it builds fine. Otherwise, keep working on it

Generate a debdiff between the Debian dsc and your modified one. Attach this debdiff to the bug report on Malone. Please check https://lists.ubuntu.com/archives/ubuntu-devel/2006-August/019922.html about how to submit debdiffs.

See also ["ReviewingTips"]. Update the status of the bug depending on the work you did.

Don't forget to report the bugs (including to the Debian BTS if needed, see ContributingToDebian) and send the patches upstream.

Get your work uploaded

https://lists.ubuntu.com/archives/ubuntu-devel/2006-August/019922.html

Check the Build Daemons on https://launchpad.net/ubuntu/+builds

Once the package is built on all archs please mark the bug as fixed. If you're using the MOTU-tools, use ./lpbugs.py -c -b <bugid>

["CategoryMOTU"]