Merging
Include(MOTU/Headers/WikiMergeUbuntuDev)
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) 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.
Useful tools
For the time being we have two main tools available but work is on-going to merge (pun intended) them:
[http://merges.ubuntu.com/ (MoM)] The official merge system, hosted on merges.ubuntu.com.
[http://dad.dunnewind.net/ (DaD)] The unofficial alternative.
Both tools have a corresponding script available that can be run locally in your machine to grab all the files needed for the merge. The MoM script is [http://merges.ubuntu.com/grab-merge.sh here].
Once downloaded remember to change its executable bits with chmod +x. You may also want to save it in a directory in your path, for instance ~/bin.
How to work on merges and syncs
There are several ways of merging packages. The one described here is merely a suggestion, but contains the mandatory steps.
Check for needed merges
Fire up your tool! We will use for this example MoM, therefore open this page:
All merges are sorted by component: main, restricted, universe and multiverse. Lets suppose we will work on a package in universe, therefore lets click on universe, or go directly to http://merges.ubuntu.com/universe.html.
You will see now all outstanding merges, listed in alphabetical order. In the left column, titled package, you will see the source package name, and its associated binary packages. There are two links here:
- One point to a REPORT, which gives general information about the merge, and possible conflicts detected. It would be very usefull to read it before starting to work on the merge.
- Another point to the source package page in launchpad. You may check there what the package is about, and check as well for any open bug reports.
In the second column, you will see:
- The maintainer of the last Ubuntu package (the one listed in the changelog)
- The uploader of the last Ubuntu package
- The version of the last Ubuntu package
Before starting to work on the merge, you should check with the previous maintainer and/or the previous uploader, if they intend to work on the merge themselves. They might give you useful tips as well, even if they delegate the task to you.
The last two columns give the Debian version we want to merge from, as well as the previous Debian version (often called the base version).
Get the files you need
The first thing to do is to get the package sources. Since we are using MoM, we will use for this example the grab-merge.sh script from MoM.
- Create an an-hoc directory and enter it.
- Fetch all the needed files with grab-merge.sh. If grab-merge.sh is in a directory in your path, use:
grab-merge.sh <sourcepackagename>
- Once all the files are downloaded, check again REPORT. It contains usefull information on the merge, as well as tips on possible conflicts.
Check if its a merge or a sync
- Check the "old ubuntu".patch file to check what has been modified by Ubuntu in previous versions and why.
- Check the "new debian".patch file to check what changes have been implemented by Debian in this new version.
- tip: you may want to use filterdiff to filter out all changes external to /debian.
- 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 changes are still necessary.
If all the Ubuntu changes can be dropped, you need to file a [https://wiki.ubuntu.com/SyncRequestProcess sync bug].
File a merge bug
Before you work on the merge, file a bug in [http://launchpad.net/ubuntu/+filebug Launchpad] against the source-package product:
Set the bug title to: Please merge <sourcepackagename><version> (repository) from Debian <repository> (<component>)
- For instance: Please merge zoph 0.7.0.2-2 (universe) from Debian unstable (main)
- Set the bug status to "in-progress" and assign it to yourself.
- If you can, set the importance to "wishlist".
- Note down the bug number, you will need it later.
Work on the merge
So there are still changes to carry over from Ubuntu to the Debian package source? Look closely at the patches provided and try to make the minimal change to set the package right.
You should check as well any open bug report, maybe your merge will close some of them, or perhaps there is a simple fix that you can include in your merge.
An already patched source tree has been prepared by the tool in the directory you have chosen. You should browse it, check that all the relative Ubuntu changes have been applied, and resolve any conflict. grab-merge.sh could already indicate some conflicts; they are marked as follows in the relative source file(s):
<<<<<<< packagename-version (ubuntu) changes from ubuntu here maybe several lines long ======= original debian lines again its possible that there are several lines of them >>>>>>> packagename-version (debian)
You should manually resolve the conflict choosing either version (or possibly "merging" them together).
Once you're done patching the package, don't forget to update debian/changelog. Use dch to update the file, or modify it manually. Add as many infos as necessary to make your changes fully understandable. Check also that the new package version is set correctly (should be -Xubuntu1, where X is the Debian version on which the merge is done) and that the distribution is correct.
Remember that you should list ALL Ubuntu changes that were carried over. Remember to add an (LP: #xxxxx) metatag where xxxxx is your merge bug report number and remove any previous metatag. Remember to add your name and email too in place of "Ubuntu Merge-o-Matic <mom@ubuntu.com>"!
Build, check and report
After you're done with this, rebuild the package with debuild -S, and check that it builds and install without errors.
If everything goes well, you should generate two [https://wiki.ubuntu.com/MOTU/Recipes/Debdiff debdiffs]: one between the Debian .dsc and your modified one and another one between the old ubuntu .dsc and your modified one. Check both debdiffs for anything which is extraneous to your changes. If needed, filter out any extraneous changes, either manually or with filterdiff.
Please check that your debdiff is of an acceptable size before uploading it; this is especially usefull for the debdiff between the old Ubuntu package and your modified one, that will contain all upstream changes too. If the size is too big, just leave a comment to the sponsors that you have it available and can upload it if necessary.
Attach these debdiffs to the bug report, un-assign yourself, set the status to "confirmed" and subscribe (not assign!) the relative [https://wiki.ubuntu.com/MOTU/Sponsorship/SponsorsQueue sponsor] (ubuntu-universe-sponsor for packages in universe, ubuntu-main-sponsors for packages in main).
Don't forget to check if the Ubuntu changes have not been reported to Debian and/or upstream already, and if not, report them.
Get your work uploaded
Check from time to time your bug report (you should be warned if changes or additions are made) and work on any comment the sponsors may have. Once accepted, your bug report will be automagically closed by your (LP: #xxxxx) metatag.
Thanks for your contribution!
Go back to [:MOTU].BR ["CategoryMOTU"]BR ["CategoryMOTUUbuntuDevMerge"]