ubuntu-packaging-guide-team team mailing list archive

[Barry Warsaw <barry@xxxxxxxxxxxxx>]

Review: Needs Fixing
=== added file 'patches-to-packages.rst'
--- patches-to-packages.rst	1970-01-01 00:00:00 +0000
+++ patches-to-packages.rst	2011-07-22 13:03:22 +0000
@@ -0,0 +1,168 @@
+===================
+Patches to Packages
+===================
+
+Very often the sources from upstream need changes to work satisfactory.  Maybe
+there is a bug fix to the released version that needs added or a change to the
+build system needed only by Ubuntu.  We keep these changes as patches, also
+called diff files.

I find this a little difficult to parse.  What do you think about this text:

"Sometimes, Ubuntu package maintainers have to change the upstream source code
in order to make it work properly on Ubuntu.  Examples include, patches to
upstream that haven't yet made it into a released version, or changes to the
upstream's build system needed only for building it on Ubuntu.  We could
change the upstream source code directly, but doing this makes it more
difficult to remove the patches later when upstream has incorporated them, or
extract the change to submit to the upstream project.  Instead, we keep these
changes as separate patches, in the form of diff files."

+There are a number of different ways of handling patches in Debian packages,
+fortunately we are standardising on one system, Quilt, which is now used by
+most packages.

There really isn't fantastic documentation on Quilt out there, but perhaps
link to this page, which is tops on Google and does have some useful
information.  Maybe link "Quilt" to it?

http://wiki.debian.org/UsingQuilt

+Let's look at an example package, ``kamoso`` in Natty::
+
+    $ bzr branch ubuntu:natty/kamoso
+
+The patches are kept in ``debian/patches``.  This package has one patch
+``kubuntu_01_fix_qmax_on_armel.diff`` to fix a compile failue on ARM.  The

s/failue/failure/

+patch has been given a name to describe what it does, a number to keep the
+patches in order (two patches can overlap if they change the same file) and in
+this case the Kubuntu team adds their own prefix to show the patch comes from
+them rather than from Debian.
+
+The order of patches to apply is kept in ``debian/patches/series``.
+
+Patches with Quilt
+------------------
+
+Before working with Quilt you need to tell it where to find the patches.  Add
+this to your ``~/.bashrc``::
+
+    export QUILT_PATCHES=debian/patches
+
+And source the file to apply the new export::
+
+    $ . ~/.bashrc
+
+By default all patches are applied already to UDD checkouts or downloaded
+packages.  You can check this with::
+
+    $ quilt applied
+    kubuntu_01_fix_qmax_on_armel.diff
+
+If you wanted to remove the patch you would run ``pop``::
+
+    $ quilt pop
+    Removing patch kubuntu_01_fix_qmax_on_armel.diff
+    Restoring src/kamoso.cpp
+
+    No patches applied
+
+And to apply a patch you use ``push``::
+
+    $ quilt push
+    Applying patch kubuntu_01_fix_qmax_on_armel.diff
+    patching file src/kamoso.cpp
+
+    Now at patch kubuntu_01_fix_qmax_on_armel.diff
+
+
+Adding a New Patch
+-------------------
+
+To add a new patch you need to tell Quilt to create a new patch, tell it which
+files that patch should change, edit the files then refresh the patch::

I think it's worth emphasizing that you really have to do the `quilt add`
before you modify the source code.  Otherwise, it's a huge pain to get those
changes into the quilt patch, at least IME.  It's the one thing I really
dislike about quilt. ;)

+    $ quilt new kubuntu_02_programme_description.diff
+    Patch kubuntu_02_programme_description.diff is now on top
+    $ quilt add src/main.cpp
+    File src/main.cpp added to patch kubuntu_02_programme_description.diff
+    $ sed -i "s,Webcam picture retriever,Webcam snapshot programme,"
+    src/main.cpp
+    $ quilt refresh
+    Refreshed patch kubuntu_02_programme_description.diff
+
+The change will now be in
+``debian/patches/kubuntu_02_programme_description.diff`` and the ``series``
+file will have had the new patch added to it.  You should add the new file to
+the packaging::
+
+    $ bzr add debian/patches/kubuntu_02_programme_description.diff
+    $ bzr add .pc/*

Here's where we get into the horror of quilt/udd compatibility.  You might
want to ask for additional suggestions from the udd mailing list, but what I
do is generally to ignore or revert the .pc changes.  One thing I've learned
with udd+quilt though is, everybody's got a different way of dealing with it
and none are right or wrong (just right-ish and wrong-esque ;).

+    $ dch -i "Add patch kubuntu_02_programme_description.diff to improve the programme description"
+    $ bzr commit
+
+Quilt keeps its metadata in the ``.pc/`` directory, so currently you need to
+add that to the packaging too.  This should be improved in future.

And then we will all rejoice. :)

+
+As a general rule you should be careful adding patches to programmes unless
+they come from upstream, there is often a good reason why that change has not
+already been made.  The above example changes a user interface string for
+example, so it would break all translations.  If in doubt, do ask the upstream
+author before adding a patch.
+
+Upgrading to New Upstream Versions
+-----------------------------------
+
+When you upgrade to a new upstream version patches will often become out of

s/version patches/version, patches/

+date.  They might need to be refreshed to match the new upstream source or they
+might need to be removed altogether.
+
+You should start by ensuring no patches are applied::
+
+    $ quilt pop -a
+    $ bzr commit -m "remove patches"  #FIXME needing this is ugly
+
+Then upgrade to the new version
+
+    $ bzr merge-upstream --version 2.0.2 https://launchpad.net/ubuntu/+archive/primary/+files/kamoso_2.0.2.orig.tar.bz2

I think you no longer need the --version option, since I think merge-upstream
can deduce that now.

+
+Then apply the patches one at a time to check for problems::
+
+    $ quilt push
+    Applying patch kubuntu_01_fix_qmax_on_armel.diff
+    patching file src/kamoso.cpp
+    Hunk #1 FAILED at 398.
+    1 out of 1 hunk FAILED -- rejects in file src/kamoso.cpp
+    Patch kubuntu_01_fix_qmax_on_armel.diff can be reverse-applied
+
+If it can be reverse-applied this means the patch has been applied already by
+upstream, so we can delete the patch::
+
+    $ quilt delete kubuntu_01_fix_qmax_on_armel
+    Removed patch kubuntu_01_fix_qmax_on_armel.diff
+
+Then carry on::
+
+    $ quilt push
+    Applied kubuntu_02_programme_description.diff
+
+It is a good idea to run refresh, this will update the patch relative to the
+changed upstream source::
+
+    $ quilt refresh
+    Refreshed patch kubuntu_02_programme_description.diff
+
+Then commit as usual::
+
+    $ bzr commit -m "new upstream version"
+
+
+Making A Package Use Quilt
+-----------------------------
+
+Modern packages use Quilt by default, it is built into the packaging
+format.  Check in ``debian/source/format`` to ensure it says ``3.0
+(quilt)``.

Actually, you can run what-patch(1) to tell you which patch system the package
is using, if any.  One thing is that Debian developers don't like it when you
switch patch systems on them, so you need to keep and use any previously
existing system.  But if the package is "patch-less" then use quilt.

+
+Older packages using source format 1.0 will need to explicity use
+Quilt, usually by including a makefile into ``debian/rules``.

s/explicity/explicitly/

Probably best to just use the existing older patch system, otherwise it makes
it more difficult to submit fixes to Debian.

+
+
+Other Patch Systems
+--------------------
+
+Other patch systems used by packages include ``dpatch`` and ``cdbs
+simple-patchsys``, these work similarly to Quilt by keeping patches in
+debian/patches but have different commands to apply, unapply or create patches.
+You can use ``edit-patch``, shown in previous chapters, as a reliable way to
+work with all systems.
+
+Even older packages will include changes directly to sources and kept in the
+``diff.gz`` source file.  This makes it hard to upgrade to new upstream
+versions or differentiate between patches and is best avoided.
+
+Bazaar Loom is a way to keep patches as part of bzr trees, see :doc:`Working
+with Patches via Loom</udd-patchsys>` for more information.

-- 
https://code.launchpad.net/~jr/ubuntu-packaging-guide/05-patches/+merge/68562
Your team Ubuntu Packaging Guide Team is subscribed to branch lp:ubuntu-packaging-guide.