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: mp+135286@code.launchpad.net

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: http://paste.ubuntu.com/1374448/.

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 :

Done.

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).
10
11 [ Dmitry Shachnev ]
12 * Fix search not working (LP: #814679).
13
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.
19
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.
24
25 Let's look at an example package, ``kamoso`` in Natty::
26@@ -164,20 +164,20 @@
27
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.
38
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.
42
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.
45-
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.
49
50 .. _`Quilt`: http://wiki.debian.org/UsingQuilt
51 .. _`bug 815854`: https://bugs.launchpad.net/bzr-builddeb/+bug/815854
52+.. _`previous chapters`: ./fixing-a-bug.html#work-on-a-fix
53
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 @@
58-======================
59- Working with Patches
60-======================
61-
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).
71-
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.
77-
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.
82-
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.
87-
88-
89-Patches are applied in source branches
90-======================================
91-
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!
99-
100-
101-Merging from Debian with quilt patches
102-======================================
103-
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.
110-
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::
113-
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
120-
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
125-would.
126-
127-
128-Develop your patch
129-==================
130-
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).
136-
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::
139-
140- $ bzr init-repo dbus
141- $ cd dbus
142- $ bzr branch ubuntu:dbus precise
143- $ bzr branch precise bug-12345
144- $ cd bug-12345
145-
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::
149-
150- $ bzr stat
151- modified:
152- README
153-
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
157-diff``::
158-
159- $ bzr diff -p "a/:b/" > ../bug-12345.patch
160-
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).
165-
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.
169-
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::
173-
174- $ quilt import ../bug-12345.patch
175- $ bzr add debian/patches/bug-12345.patch
176-
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
180-import``.
181-
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.
187-
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.
195-
196-
197-Gotchas
198-=======
199-
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.
210-
211-
212-edit-patch
213-==========
214-
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.
221-
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.
232-
233-
234-.. _quilt: http://www.wzdftpd.net/blog/index.php?2008/02/05/3-quilt-a-patch-management-system-how-to-survive-with-many-patches
235-.. _`currently includes any existing .pc directory`: https://bugs.launchpad.net/udd/+bug/672740
236-.. _`a different patch system`: http://wiki.debian.org/debian/patches

Subscribers

People subscribed via source and target branches