Merge lp:~andrewsomething/ubuntu-packaging-guide/patches-cleanup into lp:ubuntu-packaging-guide

Proposed by Andrew Starr-Bochicchio
Status: Merged
Merged at revision: 211
Proposed branch: lp:~andrewsomething/ubuntu-packaging-guide/patches-cleanup
Merge into: lp:ubuntu-packaging-guide
Diff against target: 236 lines (+9/-186)
3 files modified
debian/changelog (+2/-0)
ubuntu-packaging-guide/patches-to-packages.rst (+7/-7)
ubuntu-packaging-guide/udd-patchsys.rst (+0/-179)
To merge this branch: bzr merge lp:~andrewsomething/ubuntu-packaging-guide/patches-cleanup
Reviewer Review Type Date Requested Status
Daniel Holbach Approve
Review via email:

Description of the change

Tweaks patches-to-packages a little bit and drops udd-patchsys completely.

To post a comment you must log in.
Revision history for this message
Daniel Holbach (dholbach) wrote :

Thanks a bunch. I took the liberty to remove udd-patchsys from the index file also.

review: Approve
Revision history for this message
Dmitry Shachnev (mitya57) wrote :

> _`previous chapters`: ./fixing-a-bug.html#work-on-a-fix

Such links won't work in PDF or even single-HTML mode. It's better to use :doc: or :ref: roles which will work always, something like this:

Can I commit that?

Revision history for this message
Daniel Holbach (dholbach) wrote :

Sure, please do.

Revision history for this message
Dmitry Shachnev (mitya57) wrote :


Revision history for this message
Daniel Holbach (dholbach) wrote :

Thanks a lot!

Preview Diff

[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1=== modified file 'debian/changelog'
2--- debian/changelog 2012-11-11 09:53:29 +0000
3+++ debian/changelog 2012-11-21 00:21:21 +0000
4@@ -8,6 +8,8 @@
5 - Modify LANGS variable in Makefile when a language reaches
6 threshold (LP: #1067288).
7 - Clean up to make PEP8 compliant.
8+ * Drop udd-patchsys article. The patches-to-packages article
9+ is the recommended workflow (LP: #973884).
11 [ Dmitry Shachnev ]
12 * Fix search not working (LP: #814679).
14=== modified file 'ubuntu-packaging-guide/patches-to-packages.rst'
15--- ubuntu-packaging-guide/patches-to-packages.rst 2012-10-19 09:44:44 +0000
16+++ ubuntu-packaging-guide/patches-to-packages.rst 2012-11-21 00:21:21 +0000
17@@ -12,7 +12,7 @@
18 changes as separate patches, in the form of diff files.
20 There are a number of different ways of handling patches in Debian packages,
21-fortunately we are standardising on one system, `Quilt`_, which is now used by
22+fortunately we are standardizing on one system, `Quilt`_, which is now used by
23 most packages.
25 Let's look at an example package, ``kamoso`` in Natty::
26@@ -164,20 +164,20 @@
28 Other patch systems used by packages include ``dpatch`` and ``cdbs
29 simple-patchsys``, these work similarly to Quilt by keeping patches in
30-debian/patches but have different commands to apply, un-apply or create patches.
31-You can use ``edit-patch``, shown in previous chapters, as a reliable way to
32-work with all systems.
33+``debian/patches`` but have different commands to apply, un-apply or create
34+patches. You can find out which patch system is used by a package by using the
35+``what-patch`` command (from the ``ubuntu-dev-tools`` package). You can use
36+``edit-patch``, shown in `previous chapters`_, as a reliable way to work with
37+all systems.
39 In even older packages changes will be included directly to sources and kept
40 in the ``diff.gz`` source file. This makes it hard to upgrade to new upstream
41 versions or differentiate between patches and is best avoided.
43-Bazaar Loom is a way to keep patches as part of bzr trees, see :doc:`Working
44-with Patches via Loom<./udd-patchsys>` for more information.
46 Do not change a package's patch system without discussing it with the Debian
47 maintainer or relevant Ubuntu team. If there is no existing patch system then
48 feel free to add Quilt.
50 .. _`Quilt`:
51 .. _`bug 815854`:
52+.. _`previous chapters`: ./fixing-a-bug.html#work-on-a-fix
54=== removed file 'ubuntu-packaging-guide/udd-patchsys.rst'
55--- ubuntu-packaging-guide/udd-patchsys.rst 2012-03-20 22:02:49 +0000
56+++ ubuntu-packaging-guide/udd-patchsys.rst 1970-01-01 00:00:00 +0000
57@@ -1,179 +0,0 @@
59- Working with Patches
62-Many existing packages that have changes from upstream express those changes
63-using a patch system, of which there are several to choose from. Usually,
64-when you make an additional change to a package, you'll want to add a patch
65-file to the patch system being used, rather than editing the source code in
66-place. Note however that it is considered bad practice to add a patch system
67-to a package that does not already have one. In that case, either coordinate
68-with the Debian maintainer, or edit the files in place. You can find out if
69-your package has a patch system by using the ``what-patch`` command (from the
70-``ubuntu-dev-tools`` package).
72-While Debian has several patch systems, Quilt_ is becoming the most popular.
73-Quilt acts something like a version control system itself, and in the context
74-of UDD, this can be both a good thing and a bad thing. With Bazaar 2.5 and
75-``bzr-builddeb`` 2.8.1 (in Ubuntu 12.04 Precise), handling source packages
76-with quilt patches has become much easier.
78-There are two main tasks where you'll have to be aware of quilt patches, when
79-developing your own patch to the upstream code, and when merging new versions
80-of the package from Debian where either the Debian or Ubuntu (or both) have
81-quilt patches in the source branch.
83-Here are some guidelines for working with quilt patches in UDD in these two
84-scenarios. Some of these techniques are works-in-progress, so you should
85-adapt them to your own workflow, and keep watching for improvements from the
86-Bazaar teams.
89-Patches are applied in source branches
92-One important thing to keep in mind: all source branches reflect the tree
93-after a ``quilt push -a``. In other words, when you branch a source branch
94-from Launchpad, you get the tree with all patches applied, ready for you to
95-jump right into hacking. You do not need to ``quilt push -a`` manually, and
96-in fact, you'll get a tree with lots of distracting modifications if you push
97-or pop all the changes. Or to put it another way, once you have a branch,
98-jump right in!
101-Merging from Debian with quilt patches
104-With newer versions of Bazaar as mentioned above, merging new Debian versions
105-to Ubuntu versions should be quite easy now, even when one or both packages
106-have quilt patches. Just use ``bzr merge`` as you normally would. Under the
107-hood, Bazaar will first un-apply all the patches, then do the merge, then if
108-there are no conflicts, it will re-apply the patches leaving you again with a
109-source branch in the ``quilt push -a`` state.
111-For example, if we want to merge the Debian version of the ``aptitude``
112-package with the Ubuntu version, we would do something like this::
114- $ bzr init-repo aptitude
115- $ cd aptitude
116- $ bzr branch ubuntu:aptitude precise
117- $ bzr branch debianlp:aptitude wheezy
118- $ cd precise
119- $ bzr merge ../wheezy
121-If there are merge conflicts, the quilt patches will remain un-applied so that
122-you can resolve the conflicts more easily. You would use a combination of bzr
123-and quilt commands to resolve the conflicts, until all the quilt patches are
124-applied again. Then you're ready to commit, push, and build as you normally
128-Develop your patch
131-There is a strong preference to fixing packages using a patch system like
132-quilt, rather than modifying the source code directly. This is because with a
133-patch system, it's easier to communicate those changes to Debian or upstream
134-(where UDD isn't used), and to remove patches when upstream fixes the bug the
135-patch addresses (possibly in a completely different way).
137-Let's say there's a bug in the ``dbus`` package that you want to fix. You
138-start the way you normally would with any package in UDD::
140- $ bzr init-repo dbus
141- $ cd dbus
142- $ bzr branch ubuntu:dbus precise
143- $ bzr branch precise bug-12345
144- $ cd bug-12345
146-Maybe the bug is pretty simple; there's a typo in the ``README`` file. Just
147-fix the typo in your favorite editor, then do a ``bzr stat`` to prove that the
148-file has been edited::
150- $ bzr stat
151- modified:
154-Now, in order to get this fix into a quilt patch, we need to generate a diff,
155-but we need the resulting patch to have a format that is consumable by quilt.
156-The way to do that is to use the ``--prefix`` (or ``-p``) option to ``bzr
159- $ bzr diff -p "a/:b/" > ../bug-12345.patch
161-What this actually does is to produce a *level 1* diff, which is required by
162-the quilt command we're going to use below. Normally, ``bzr diff`` produces
163-*level 0* diffs which are more easily read by humans, but this won't work with
164-quilt (despite the implication in the quilt documentation).
166-The above command generates the patch and stores it in a file one level up
167-from the working tree. Note that here we're using the ``a`` and ``b``
168-directory prefixes for the diff, but the actual names don't really matter.
170-Now all you need to do is to import the patch into your quilt patches. If you
171-named the file above with the same name you want into your quilt stack, then
172-just do this::
174- $ quilt import ../bug-12345.patch
175- $ bzr add debian/patches/bug-12345.patch
177-You need the last line to inform Bazaar about the new quilt patch file. You
178-can see that the quilt patch's name is the same as the file name you generated
179-above. Of course, you can change this by using the ``-P`` option to ``quilt
182-One important thing to notice is that if you do the commands ``bzr stat`` and
183-a ``quilt applied`` , you'll see that the ``README`` file is still modified,
184-but the ``bug-12345.patch`` is not yet applied. If you try to apply the newly
185-imported quilt patch (with ``quilt push``), it will fail because you're
186-applying a patch on top of the already patched file.
188-One way around this is to revert the change to ``README`` before doing the
189-``quilt push``. However, if you think you may want to continue to develop the
190-patch, and thus do not want to throw away your in-tree changes, use ``bzr
191-shelve`` to save the change in the working tree to the side, then do ``quilt
192-push``. Either way, once you've pushed your top quilt patch, you can just
193-edit the tree in place, and do ``quilt refresh`` commands to update the top
194-quilt patch.
200-One thing to keep in mind is that quilt uses a hidden ``.pc`` directory to
201-record its status. This directory is under version control in all source
202-branches. *Watch out* for changes to the ``.pc`` directory that are unrelated
203-(or more accurately, uninteresting) to your patch. This can happen because
204-the UDD source branch importer `currently includes any existing .pc
205-directory`_ in the imported branch. This can cause conflicts, or other
206-unwanted or unknown changes because you've essentially got two conflicting
207-version control systems competing for the same thing (i.e. bzr and quilt).
208-For now, the best recommendation is to revert any changes to the ``.pc``
209-directory in your branch.
215-``edit-patch`` is a nice little wrapper script that comes as part of the
216-``ubuntu-dev-tools`` package. It pretty much hides the nasty details of
217-dealing with the patch system specifically. For example, while the above
218-works well if your package is using quilt already, you'll have to adjust the
219-workflow, perhaps significantly, to work with `a different patch system`_. In
220-theory ``edit-patch`` should solve this, but there are currently two blockers.
222- * By default, ``bzr diff`` produces a ``-p0`` patch, but ``edit-patch``
223- defers to the underlying patch system's default. For quilt, this is
224- ``-p1``. ``quilt import`` takes a ``-p`` argument to specify the prefix
225- level, but this isn't yet exposed in ``edit-patch``. If you use the
226- ``--prefix`` argument to the ``bzr diff`` command as shown above, you
227- should be okay.
228- * By default, ``edit-patch`` requires a path to an existing patch file, but
229- it's more convenient to pipe the output of ``bzr diff`` to the stdin of
230- ``edit-patch``, as shown above. The alternative would be to save the diff
231- in a temporary file, and then point ``edit-patch`` to this temporary file.
234-.. _quilt:
235-.. _`currently includes any existing .pc directory`:
236-.. _`a different patch system`:


People subscribed via source and target branches