1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
Loom, a plugin for bzr to assist in developing focused patches.
Copyright (C) 2006 Canonical Limited.
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 2 as published
by the Free Software Foundation.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
A quick guide to using looms
++++++++++++++++++++++++++++
Overview
========
Loom is used to build up a new version of a source tree on top of an upstream
version.
Installation
============
Loom is most easily installed by symlinking its source directory to
~/.bazaar/plugins/loom. Alternatively you can install it for the entire machine
using setup.py --install.
You can verify that loom is installed by running`` bzr plugins`` and looking
for loom in the output.
Getting Started
===============
1. The first thing to do is to convert a upstream version branch into a loom.
In this example I call the upstream 'upstream'. In your upstream branch run::
% bzr nick upstream
% bzr loomify
This will convert your branch to a loom - at this point you will require the
loom plugin to use bzr on it. It will also create a thread called 'upstream'.
If you do 'bzr push' to a new branch now, it will make the remote branch be a
loom as well. If you push to an existing normal bzr branch, then the current
thread of your loom is what will be pushed. You can use this to publish
individual threads for people that do not have the loom plugin.
1. Now you can create another thread, which will represent the first patch
you are building on top of the 'upstream'.
% bzr create-thread "demo-patch"
This creates the new thread after your current thread, and switches you onto
it. You can see what thread you are on using::
% bzr show-loom
Look for the '=>' marker beside the thread you are on. The output represents
a stack of threads - at the top is the thread you are working towards, below
that are the threads that it depends upon. At the very bottom is the thread
that represents the upstream release being built upon.
Working with the loom
=====================
You can now work with the thread you are in just like a normal bzr branch -
you can pull work from a normal branch into it, perform commits, uncommits,
look at bzr log etc. There are however additional commands that you can use -
they are covered in the following sections. For more information on them, use
``bzr help command-name``.
Starting a new patch
--------------------
When you make a new patch, you need to decide where in the loom it should go.
Best practice is to put the thread for this new patch as close to the upstream
as makes sense. For instance, if you are a debian maintainer with the following loom::
=>debian
update configure for 2.59
fix 64-bit compilation
upstream
And you have received a bug report with patch which corrects a typographical
error in the manual, you could put this in one of the existing threads - but
none fit that well. You could put it above the debian thread, but it does not
depend on the debian thread, and the debian thread *does* depend on it,
because the debian thread represents what you will be uploading to the distro.
You could put it above the configure update, or the 64-bit compilation fix, or
right above upstream.
So where to put it?
If none of the threads are in the process of being merged into upstream, and
this is something you plan to send upstream immediately then
the best place for this new thread is probably right next to upstream.
On the other hand, if the fix-64 bit and update-configure threads are already
in the process of being merged into upstream, then the best place for the new
thread is after the update configure thread.
To create the thread after the update-configure thread, use down-thread once
to switch to the update configure script thread, and then invoke
create-thread::
% bzr down-thread
% bzr create-thread documentation-fixes
Now you can apply the patch and commit it::
% patch -0 < doco-fix.patch
% bzr commit
Updating to a new upstream version
----------------------------------
When upstream makes a new release, you need to bring their changes into your
baseline thread - the bottom thread, and then merge the changes up through your
loom to the top thread.
1. Firstly, use ``down-thread`` repeatedly to move down to the bottom thread
of the loom (this will be made easier in the future with an automatic mode of
operation)::
% bzr down-thread
% bzr down-thread
% bzr down-thread
% bzr show-loom
debian
update configure for 2.59
fix 64-bit compilation
=>upstream
1. Now pull the new upstream release. You can use bzr pull or bzr merge for
this, depending on whether you want the upstream branch to be a clone of the
upstreams branch, or to reflect the times that you have updated to upstream::
% bzr pull UPSTREAM-URL
1. Integrating the changes from upstream into your loom is straightforward
now. When you go up a thread bzr will automatically perform a merge, and you
simply need to check that the merge came out correctly and then commit it. If
you are sure it has come out correctly, you can just commit straight away.
(Again, this will be made slicker and more automated in the future). In our
example, where we have 64-bit bugfixes in the stack, its quite likely that
upstream will cause regressions in new code they are writing, so I'd be
inclined to do a detailed diff to see what changes they have brought in...::
% bzr up-thread
All changes applied successfully.
Moved to thread 'fix 64-bit compilation'.
% bzr diff
% bzr st
% bzr commit -m 'New upstream release.'
1. Just repeat these steps to move up through the loom to the top. Once you
reach the top, you are fully updated to upstream, and you've adjusted every
thread to the new release. This is a good time to record your loom, so that
you can push the new release::
% bzr record "Update to 1.2."
When upstream have merged a patch
---------------------------------
When you are doing an update to upstream and they have merged a patch, your
thread will suddenly lose all its changes. Lets say in the example above that
upstream have merged the autoconf update. When you are updating that thread,
add in a call to ``diff -r thread:`` and you will see no changes.
% bzr up-thread
All changes applied successfully.
Moved to thread 'update configure for 2.59'.
% bzr diff -r thread:
Because there are no changes to the thread below, this thread has been fully
merged, and unless you are planning further configure changes, you don't need
it in your stack anymore. The way to remove it is to use ``combine-thread``.
``combine-thread`` is the reverse of ``create-thread`` - where
``create-thread`` makes a new thread above the current one, ``combine-thread``
combines the current thread into the one below it.::
% bzr show-loom
debian
=>update configure for 2.59
fix 64-bit compilation
upstream
% bzr combine-thread
% bzr show-loom
debian
=>fix 64-bit compilation
upstream
|