3 |
============================================================= |
============================================================= |
4 |
|
|
5 |
:Author: Tuomas J. Lukka |
:Author: Tuomas J. Lukka |
6 |
:Last-Modified: $Date$ |
:Status: Current |
|
:Revision: $Revision$ |
|
|
:Status: Incomplete |
|
7 |
|
|
8 |
Having the FenPDF prototype in production use requires more |
Having the FenPDF prototype in production use requires more |
9 |
stability than we've needed so far. CVS is not good for |
stability than we've needed so far. CVS is not good for |
10 |
branching and inspection of commits *before* allowing |
branching and inspection of commits *before* allowing |
11 |
them into the official tree. |
them into the official tree. |
12 |
|
|
13 |
I propose we move to arch, at the latest |
I propose we move to arch. |
14 |
the moment version 1.1 (with star-merge) |
|
|
is finished, and start testing the 1.1 pre versions |
|
|
right away. |
|
15 |
|
|
16 |
Issues |
Issues |
17 |
====== |
====== |
21 |
Changes |
Changes |
22 |
======= |
======= |
23 |
|
|
24 |
|
(to be moved to docs/ upon acceptance) |
25 |
|
|
26 |
The fenfire projects will be moved out of CVS and into arch. |
The fenfire projects will be moved out of CVS and into arch. |
27 |
|
CVS commits will be disabled except for project managers: mirroring |
28 |
|
the arch trees to CVS is desirable. |
29 |
|
|
30 |
The arch categories |
The arch categories |
31 |
of the projects will be named with the current CVS directory names:: |
of the projects will be named with the current CVS directory names:: |
32 |
|
|
36 |
callgl |
callgl |
37 |
controllers |
controllers |
38 |
fenfire |
fenfire |
|
fenfire-cvs |
|
39 |
fenfire-depends |
fenfire-depends |
|
fenfire-priv |
|
40 |
libvob |
libvob |
41 |
libvob-depends |
libvob-depends |
42 |
loom |
loom |
47 |
storm |
storm |
48 |
storm-depends |
storm-depends |
49 |
|
|
50 |
Each project will have two official |
The official fenfire archive |
51 |
branches: ``devel`` and ``semistable`` (later, a ``stable`` branch |
---------------------------- |
52 |
may be added). |
|
53 |
|
The official fenfire archive will be named :: |
54 |
|
|
55 |
|
fenfire@fenfire.org--2003 |
56 |
|
|
57 |
|
initially located in Himalia. It shall be made accessible through http |
58 |
|
as well as sftp. |
59 |
|
|
60 |
|
In it, each subproject will have a single mainline branch: ``dev``, |
61 |
|
with other branches (e.g. ``testing``, ``stable``) to be added later. |
62 |
|
|
63 |
The greatest change from the previous development model |
The greatest change from the previous development model |
64 |
is that **only the project maintainer may check in to these branches**. |
is that **only the project maintainer (tjl) may check in to the official archive**. |
65 |
|
|
66 |
This is not as bad as it sounds, as arch allows mutual merges |
This is not as bad as it sounds, as arch allows mutual merges |
67 |
and other branches between developers, so this is not limiting in any way. |
and other branches between developers, so this is not limiting in any way. |
83 |
that the maintainer will actually read the code and accept |
that the maintainer will actually read the code and accept |
84 |
or reject it (explaining why and what needs to be done for acceptance). |
or reject it (explaining why and what needs to be done for acceptance). |
85 |
|
|
86 |
|
The developers should have their own arch trees mirrored to himalia for easy merge |
87 |
|
by the project manager. |
88 |
|
|
89 |
|
Arch versions |
90 |
|
============= |
91 |
|
|
92 |
|
We need star-merge. |
93 |
|
Tla 1.1 is not yet released. |
94 |
|
|
95 |
|
Because of this, you need to get tla-1.1pre5 (or later) and compile it |
96 |
|
for yourself. |
97 |
|
|
98 |
Examples |
Examples |
99 |
======== |
======== |
100 |
|
|
101 |
How would this work, then? |
How would this work, then? |
|
(The stuff below will go to the ``docs/`` directory) |
|
|
|
|
|
How things will work at stage 1: arch on himalia for everyone to commit & update |
|
|
================================================================================ |
|
|
|
|
|
How things will work **after** the change to maintainer-oriented |
|
|
================================================================ |
|
102 |
|
|
103 |
Getting the official version |
Getting the official version |
104 |
---------------------------- |
---------------------------- |
105 |
|
|
106 |
In the following, I'll use the test archive ``lukka@iki.fi--2003-test2`` |
In the following, I'll use ``me@bar--2003`` as the local archive and ``/home/me/{archives}`` as |
107 |
and ``me@bar--2003`` as the local archive. Adjust accordingly. |
your local archive dir. Adjust accordingly. |
108 |
|
|
109 |
First, register the location of the archive you are mirroring from:: |
First, register the location of the archive you are mirroring from:: |
110 |
|
|
111 |
tla register-archive lukka@iki.fi--2003-test2-SOURCE sftp://kuu/BIG/arch/test2arch |
tla register-archive fenfire@fenfire.org--2003-SOURCE sftp://himalia.it.jyu.fi/home/lukka/{archives}/fenfire@fenfire.org--2003 |
112 |
|
|
113 |
Then, create the local mirror:: |
Then, create the local mirror to your own hard drive. |
114 |
|
You *could* use it directly but it's *safer* if we have lots of distributed |
115 |
|
mirrors:: |
116 |
|
|
117 |
tla make-archive --mirror-from lukka@iki.fi--2003-test2-SOURCE /BIG/arch/kuumirror |
tla make-archive --mirror-from fenfire@fenfire.org--2003-SOURCE /home/me/{archives}/fenfire@fenfire.org--2003 |
118 |
|
|
119 |
And finally, mirror the archive:: |
And finally, mirror the archive:: |
120 |
|
|
121 |
tla archive-mirror lukka@iki.fi--2003-test2 |
tla archive-mirror fenfire@fenfire.org--2003 |
122 |
|
|
123 |
|
The last command is what you'll repeat to get the latest changes to your mirror. |
124 |
|
|
|
The last command is what you'll repeat to get the latest changes. |
|
125 |
|
|
126 |
**IMPORTANT**: NEVER COMMIT TO THE MIRROR. Arch will complain but will leave lock files that |
**IMPORTANT**: NEVER COMMIT TO THE MIRROR. Arch will complain but may leave lock files that |
127 |
you then need to clean up properly. Not fun. |
you then need to clean up properly. Not fun. |
128 |
|
|
129 |
Next, get the official version of the full fenfire tree from the archive:: |
Next, get the official version of the full fenfire tree from the archive:: |
130 |
|
|
131 |
tla get lukka@iki.fi--2003-test2/ff--kuu--0.1 ff |
tla get fenfire@fenfire.org--2003/ff--dev--0.1 ff |
132 |
|
|
133 |
The name `ff` is the "full fenfire", i.e. all project trees of the subprojects, |
The name `ff` is the "full fenfire", i.e. all project trees of the subprojects, |
134 |
plus dependencies. The second argument is the directory name to use for the tree, |
plus dependencies. The second argument is the directory name to use for the tree, |
137 |
The `ff` tree is an ``arch`` config, i.e. they are not automatically |
The `ff` tree is an ``arch`` config, i.e. they are not automatically |
138 |
obtained but :: |
obtained but :: |
139 |
|
|
140 |
tla buildcfg devel |
tla buildcfg ff--dev--0.1 |
141 |
|
|
142 |
will get them for you. Make sure you have enough disk space. |
will get them for you. Make sure you have enough disk space. The name is the same |
143 |
|
as the branch only by choice - see ``tla`` documentation about configs. |
144 |
|
|
145 |
**IMPORTANT**: DO NOT RUN BUILDCFG TWICE OR AFTER YOU MAKE CHANGES. It copies files |
**IMPORTANT**: DO NOT RUN BUILDCFG TWICE OR AFTER YOU MAKE CHANGES. It copies files |
146 |
that are "on the way" to save directories and recovering is not fun. |
that are "on the way" to save directories and recovering is not fun. |
147 |
|
|
148 |
Using buildcfg for ff is not obligatory but it does make things easier. |
Using buildcfg for ff is not obligatory but it does make things easier. You could |
149 |
|
just as well check out all subprojects yourself. |
150 |
|
|
151 |
|
Now: the buildcfg tree is just the official version - you can't really *do* anything |
152 |
|
with it except build and run (remember symlinks for fenfire-priv and tmpimg). |
153 |
|
You should not edit it - that would be misusing arch badly. |
154 |
|
You need local branches for that. |
155 |
|
|
156 |
|
Note in the ``ff`` directory there is the ``DIRS`` file for easy foreach loops. |
157 |
|
|
158 |
Branching |
Branching |
159 |
--------- |
--------- |
162 |
and submit your changes back to the official tree. |
and submit your changes back to the official tree. |
163 |
First, create the local archive:: |
First, create the local archive:: |
164 |
|
|
165 |
tla make-archive me@bar--2003 /home/me/archives/2003 |
tla make-archive me@bar--2003 /home/me/{archives}/me@bar--2003 |
166 |
|
|
167 |
**IMPORTANT**: ``me@bar--2003`` **MUST** be unique. |
**IMPORTANT**: ``me@bar--2003`` **MUST** be unique. |
168 |
|
|
169 |
Set it as your default archive:: |
Set it as your default archive:: |
170 |
|
|
171 |
tla my-default-archive me@bar--2003 |
tla my-default-archive me@bar--2003 |
172 |
|
|
173 |
Next, create local categories for any of the trees you intend to modify. |
Next, create local categories for any of the trees you intend to modify. |
174 |
|
Let's say you don't think you'll be editing anything except fenfire |
175 |
|
(you can add more later) |
176 |
|
|
177 |
tla archive-setup fenfire--bar--0.1 |
tla archive-setup fenfire--bar--0.1 |
178 |
|
|
|
Note in the ``ff`` directory there is the ``DIRS`` file for easy foreach loops. |
|
|
|
|
179 |
Now, create the branch by tagging from the official revision:: |
Now, create the branch by tagging from the official revision:: |
180 |
|
|
181 |
tla tag lukka@iki.fi--2003-test2/fenfire--kuu--0.1 fenfire--bar--0.1 |
tla tag lukka@iki.fi--2003-test2/fenfire--kuu--0.1 fenfire--bar--0.1 |
200 |
This commit created the version ``fenfire--bar--0.1--patch-1`` from the base |
This commit created the version ``fenfire--bar--0.1--patch-1`` from the base |
201 |
version ``fenfire--bar--0.1--base-0``. |
version ``fenfire--bar--0.1--base-0``. |
202 |
|
|
203 |
|
Submitting changes |
204 |
|
------------------ |
205 |
|
|
206 |
|
There are several ways to submit it to the maintainer. The simplest (for people |
207 |
|
with accounts on himalia) is to mirror your local archive to himalia:: |
208 |
|
|
209 |
|
tla make-archive --mirror me@bar--2003 sftp://himalia.it.jyu.fi/home/me/{archives}/me@bar--2003 |
210 |
|
|
211 |
|
(it's important to have it in the ``{archives}`` subdir so that the irc archbot |
212 |
|
knows it's an archive) and then (everytime you've made a change):: |
213 |
|
|
214 |
|
tla archive-mirror me@bar--2003 |
215 |
|
|
216 |
|
mirrors the changes. |
217 |
|
|
218 |
|
Then you just inform the maintainer with a merge request:: |
219 |
|
|
220 |
|
Could you merge |
221 |
|
|
222 |
|
me@bar--2003 |
223 |
|
sftp://himalia.it.jyu.fi/home/me/{archives}/me@bar--2003 |
224 |
|
fenfire--bar--0.1--patch-1 |
225 |
|
|
226 |
|
and then things can go several ways: 1) the maintainer accepts and merges |
227 |
|
2) the maintainer rejects, saying "we don't want this change" or |
228 |
|
3) the maintainer boomerangs it back: "yes, I'll accept but change it like X and Y first". |
229 |
|
|
230 |
|
In the first case, you don't need to do anything. |
231 |
|
In the second case, you should undo the patch in your local branch by ``tla replay --reverse``. |
232 |
|
In the third case, things get interesting, especially if you have other patches |
233 |
|
after that in your archive. The project manager will want to have small, easy changes |
234 |
|
to be easily able to judge them so you *shouldn't* just make the change and send the latest |
235 |
|
version! What you should do is to make a new branch for it: |
236 |
|
|
237 |
|
tla tag lukka@iki.fi--2003-test2/fenfire--kuu--0.1 fenfire--bar-pegpatch1--0.1 |
238 |
|
|
239 |
|
and then replay that exact patch to this branch and make the changes and send a merge |
240 |
|
request for this branch. |
241 |
|
|
242 |
|
If you're making a major change you think will have issues, you are probably best off *starting* |
243 |
|
with a new branch (that's what Tjl did in the Functional branch example). |
244 |
|
|
245 |
|
|
246 |
|
If you don't have access to himalia, you can still submit patches using changesets |
247 |
|
(or by publishing your archive through http elsewhere, of course). |
248 |
|
|
249 |
Now, let's get this patch as something we can send to the maintainer:: |
Now, let's get this patch as something we can send to the maintainer:: |
250 |
|
|
251 |
tla get-patch fenfire--bar--0.1--patch-1 |
tla get-patch fenfire--bar--0.1--patch-1 |
261 |
This is an ideal case, where the patchset was directly what was wanted. |
This is an ideal case, where the patchset was directly what was wanted. |
262 |
However, in most cases, the command ``tla mkpatch`` should be used. |
However, in most cases, the command ``tla mkpatch`` should be used. |
263 |
|
|
|
Accepts, rejects, ... |
|
|
--------------------- |
|
|
|
|
|
So, then it's the maintainer's decision what to do with your patch. |
|
|
There are four possible outcomes: |
|
|
|
|
|
- Accept directly - patch applied |
|
|
|
|
|
- Accept with maintainer edits to the finished product - patch applied, |
|
|
results edited. |
|
264 |
|
|
265 |
- Boomerang (Finnish university term): you need to do some more work, |
Merging changes from the main branch |
266 |
e.g. clean up some things about the patch. For example, if your |
------------------------------------ |
|
patch doesn't apply cleanly to a recent version of the maintainer's |
|
|
tree, you need to fix it. If there's not enough javadoc, you need |
|
|
to fix it. |
|
267 |
|
|
268 |
- Reject completely: this patch is not something the maintainer wants. |
After you have made changes to your local branch, and the maintainer has accepted |
269 |
|
other peoples' patches to the main branch, you need to synch up your local tree. |
270 |
|
The ``star-merge`` command is an excellent tool for this :: |
271 |
|
|
272 |
How do you cope when some patches are accepted, some rejected? |
tla commit -L"Some changes" # Make sure you have committed things exactly |
273 |
|
tla update --in-place . # If you're using more than one checkout, make sure |
274 |
|
you're up to date |
275 |
|
|
276 |
The first rule of this is: |
tla star-merge fenfire@fenfire.org--2003/fenfire--dev--0.1 . |
277 |
|
|
278 |
**It's your problem**. |
Make note of all 'C' messages and do :: |
279 |
|
|
280 |
With arch, you **can** solve the problem, but still: the maintainer will |
find . -name '*.rej' |
|
have no qualms making any decision even when it's guaranteed to make your |
|
|
tree messy. |
|
281 |
|
|
282 |
|
afterwards to make sure nothing went wrong. |
283 |
|
|
284 |
|
|
285 |
Initial Patch policy |
Initial Patch policy |
290 |
The initial policy (at least of Tjl) is: |
The initial policy (at least of Tjl) is: |
291 |
|
|
292 |
- accept changes to Storm only from Benja |
- accept changes to Storm only from Benja |
293 |
- accept changes to Navidoc only from humppake |
- accept changes to Navidoc only from humppake (except for the data structure parts |
294 |
- accept changes to CallGL only from Jvk |
which need to be moved out) |
295 |
|
|
296 |
- accept any changes to ``lava/`` dirs |
- accept any changes to ``lava/`` dirs |
297 |
- accept any documentation / formatting cleanups if they are certain |
- accept any documentation / formatting cleanups if they are certain |