← Back to branch summary

~raoul-snyman/ubuntu-packaging-guide/new-colours

« back to all changes in this revision

Viewing changes to udd-patchsys.rst

  • Committer: Barry Warsaw
  • Date: 2011-03-09 12:41:16 UTC
  • mfrom: (20.2.10 udd)
  • Revision ID: barry@python.org-20110309124116-qqjo186rt2vxspzu
Merge Ubuntu Distributed Development documentation from the wiki into the
packaging guide.  This needs a bit more reorganization, but it's a good first
step to merging the content from the UDD wiki pages.

Show diffs side-by-side

added added

removed removed

Lines of Context:
udd-patchsys.rst
 
1
===========================
 
2
Working with a patch system
 
3
===========================
 
4
 
 
5
Many existing packages that have changes from upstream express those changes
 
6
using a `patch system`_, of which there are several to choose from.  Usually,
 
7
when you make an additional change to a package, you'll want to add a patch
 
8
file to the patch system being used, rather than editing the source code in
 
9
place.  Note however that it is considered bad practice to add a patch system
 
10
to a package that does not already have one.  In that case, either coordinate
 
11
with the Debian maintainer, or edit the files in place.  You can find out if
 
12
your package has a patch system by using the ``what-patch`` command (from the
 
13
``ubuntu-dev-tools`` package).
 
14
 
 
15
Although UDD, and in particular `Bazaar looms`_ makes it pretty easy to keep
 
16
individual patches separated, if you're submitting changes to be uploaded,
 
17
you're currently better off playing along with the package's patch system.
 
18
*You will want at least bzr loom version 2.2.1dev, otherwise you'll have
 
19
problems pushing and pulling your threads to Launchpad.* Do ``bzr plugins`` to
 
20
find the version you're using.
 
21
 
 
22
Here are some guidelines that I've found helpful.  Clearly the existing tools
 
23
can be improved, but for now this seems to work well enough.  This assumes
 
24
you're using looms to develop your patch, and that the package itself uses the
 
25
quilt_ patch system.
 
26
 
 
27
One important thing to know: all source branches reflect the tree after a
 
28
``quilt push -a``.  In other words, when you branch a source branch, you get
 
29
the tree with all patches applied, ready for you to jump right into hacking.
 
30
You do not need to ``quilt push -a`` manually, and in fact, you'll get a tree
 
31
with lots of distracting modifications if you push or pop all the changes.  Or
 
32
to put it another way, once you have a branch, jump right in!
 
33
 
 
34
 
 
35
Develop your patch
 
36
==================
 
37
 
 
38
Start as you normally would with UDD and looms::
 
39
 
 
40
    $ bzr init-repo foobar
 
41
    $ cd foobar
 
42
    $ bzr branch ubuntu:foobar
 
43
    $ bzr branch foobar bug-12345
 
44
    $ cd bug-12345
 
45
    $ bzr loomify --base trunk
 
46
    $ bzr create-thread sourcefix
 
47
 
 
48
Now that you are in the ``sourcefix`` thread, just edit the source code,
 
49
making whatever changes you need to fix the bug.  Don't worry about the patch
 
50
system at this point, at least until you are happy with your changes.  If
 
51
someone else pushes changes to the package while you're working on it, just
 
52
``bzr commit`` your current work, ``bzr down-thread`` to ``trunk``, pull the
 
53
updates, and ``bzr up-thread --auto`` back to the ``sourcefix`` thread,
 
54
resolving any conflicts along the way.  You can periodically commit your
 
55
changes, ``bzr record`` and push them to Launchpad as you go, of course
 
56
linking your branch to the bug in Launchpad.  So far, it's just normal
 
57
development with looms.
 
58
 
 
59
Once you're happy with your changes, you need to essentially import your
 
60
thread's changes into a quilt patch.  This is fairly easy to do.  While inside
 
61
the ``sourcefix`` thread do::
 
62
 
 
63
    $ bzr create-thread quiltfix
 
64
    $ bzr diff -rthread:trunk..thread:sourcefix | quilt import -p0 -P bug-12345 /dev/stdin
 
65
    $ bzr add debian/patches/bug-12345
 
66
    $ quilt push
 
67
    $ quilt pop
 
68
    $ bzr commit
 
69
 
 
70
Why the last push/pop before the commit?  The push gets the imported changes
 
71
into the quilt patch, but also leaves the tree modified, so you'll essentially
 
72
have the changes both in the ``debian/`` directory and in the source tree.
 
73
The pop undoes the tree changes (which are also available in the ``sourcefix``
 
74
thread), but leaves the quilt change available.  A ``bzr commit`` at this
 
75
point gives you a thread with just the changes to ``debian/``.
 
76
 
 
77
 
 
78
Problems
 
79
========
 
80
 
 
81
The problem comes when you want to modify the patch, e.g.::
 
82
 
 
83
    $ bzr down-thread
 
84
    <hack, commit>
 
85
 
 
86
This does *not* work well::
 
87
 
 
88
    $ bzr up-thread
 
89
 
 
90
You'd expect at this point to be able to ``quilt fold`` your new changes to
 
91
update your ``bug-12345`` quilt patch, but in fact, this doesn't work.  You can
 
92
end up with difficult to resolve conflicts, patch failures and rejections.  My
 
93
recommendation is that when you make changes to your ``sourcefix`` thread,
 
94
blow away your ``quiltfix`` thread and regenerate it.  Looms make this easy::
 
95
 
 
96
    $ bzr up-thread
 
97
    $ bzr revert
 
98
    $ bzr combine-thread --force (throws away your quiltfix changes)
 
99
    $ bzr create-thread quiltfix
 
100
    $ bzr diff -rthread:trunk..thread:sourcefix | quilt import -p0 -P bug-12345 /dev/stdin
 
101
    etc...
 
102
 
 
103
So you've thrown away the original ``quiltfix`` thread and recreated it, with
 
104
your updated ``sourcefix`` changes.
 
105
 
 
106
 
 
107
Gotchas
 
108
=======
 
109
 
 
110
One thing to keep in mind is that quilt uses a hidden ``.pc`` directory to
 
111
record its status.  This directory is under version control in all source
 
112
branches.  *Watch out* for changes to the ``.pc`` directory that are unrelated
 
113
(or more accurately, uninteresting) to your patch.  This can happen because
 
114
the UDD source branch importer `currently includes any existing .pc
 
115
directory`_ in the imported branch.  This can cause conflicts, or other
 
116
unwanted or unknown changes because you've essentially got two conflicting
 
117
version control systems competing for the same thing (i.e. bzr and quilt3).
 
118
For now, the best recommendation is to revert any changes to the ``.pc``
 
119
directory in your branch.
 
120
 
 
121
 
 
122
Publishing your changes
 
123
=======================
 
124
 
 
125
It's actually easier at this point to generate a diff for attaching to the bug
 
126
report.  While inside the ``quiltfix`` thread, just::
 
127
 
 
128
    $ bzr up-thread --auto
 
129
    $ bzr diff -rthread: > bug-12345.diff
 
130
 
 
131
The differences between the ``quiltfix`` thread and the ``sourcefix`` thread
 
132
are the interesting bits, and totally appropriate for committing and upload.
 
133
Because of the way looms interacts with Launchpad, you can still link your
 
134
branch to the bug and request a merge proposal, but understand that the diff
 
135
will include all changes between ``quiltfix`` (top) and ``trunk`` (bottom)
 
136
threads.  So the merge proposal will include the changes in the ``debian/``
 
137
directory, *and* the changes in the source tree.  As long as you and your
 
138
reviewer understands this, you should be okay, but it can be confusing at
 
139
first.
 
140
 
 
141
If you need a sponsor to merge and upload your changes, one thing they *do
 
142
not* want to do is::
 
143
 
 
144
    $ bzr branch ubuntu:foobar
 
145
    $ cd foobar
 
146
    $ bzr merge lp:~you/ubuntu/natty/foobar/yourfix
 
147
 
 
148
Much badness (in the form of infinite *maximum recursion depth* exceptions)
 
149
ensues.  Yes, we need to file a bug on that.
 
150
 
 
151
 
 
152
edit-patch
 
153
==========
 
154
 
 
155
``edit-patch`` is a nice little wrapper script that comes as part of the
 
156
``ubuntu-dev-tools`` package.  It pretty much hides the nasty details of
 
157
dealing with the patch system specifically.  For example, while the above
 
158
works well if your package is using quilt already, you'll have to adjust the
 
159
workflow, perhaps significantly, to work with `a different patch system`_.  In
 
160
theory ``edit-patch`` should solve this, but there are currently two blockers.
 
161
 
 
162
  * By default, ``bzr diff`` produces a ``-p0`` patch, but ``edit-patch``
 
163
    defers to the underlying patch system's default.  For quilt, this is
 
164
    ``-p1``.  ``quilt import`` takes a ``-p`` argument to specify the prefix
 
165
    level, but this isn't yet exposed in ``edit-patch``.  If you're
 
166
    adventurous, try changing the ``bzr diff`` command above to specify the
 
167
    proper prefixes using its ``-p`` option.
 
168
  * By default, ``edit-patch`` requires a path to an existing patch file, but
 
169
    it's more convenient to pipe the output of ``bzr diff`` to the stdin of
 
170
    ``edit-patch``, as shown above.  The alternative would be to save the diff
 
171
    in a temporary file, and then point ``edit-patch`` to this temporary file.
 
172
 
 
173
 
 
174
Future
 
175
======
 
176
 
 
177
Ideally, it would be nice to add a ``bzr edit-patch`` or some such command
 
178
which does the whole loom -> patch system import.  At least ``edit-patch``
 
179
could grow a ``-p`` and ``-P`` option, as well as read from stdin.  Stay
 
180
tuned, or get involved!
 
181
 
 
182
There's now `a bug` that tracks this.
 
183
 
 
184
 
 
185
.. _`patch system`: https://wiki.ubuntu.com/DistributedDevelopment/Documentation/PatchSystem/PackagingGuide/PatchSystems
 
186
.. _`Bazaar looms`: https://launchpad.net/bzr-loom
 
187
.. _quilt: http://www.wzdftpd.net/blog/index.php?2008/02/05/3-quilt-a-patch-management-system-how-to-survive-with-many-patches
 
188
.. _`currently includes any existing .pc directory`: https://bugs.launchpad.net/udd/+bug/672740
 
189
.. _`a different patch system`: http://wiki.debian.org/debian/patches
 
190
.. _`a bug`: https://launchpad.net/bugs/620721