/[fenfire]/fenfire/docs/pegboard/cvs_to_tla--tjl/peg.rst
ViewVC logotype

Diff of /fenfire/docs/pegboard/cvs_to_tla--tjl/peg.rst

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.5 by tjl, Thu Sep 11 17:26:08 2003 UTC revision 1.6 by tjl, Fri Sep 12 08:38:06 2003 UTC
# Line 3  PEG cvs_to_arch--tjl: Move to a better v Line 3  PEG cvs_to_arch--tjl: Move to a better v
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  ======  ======
# Line 25  Issues Line 21  Issues
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    
# Line 35  of the projects will be named with the c Line 36  of the projects will be named with the c
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
# Line 48  of the projects will be named with the c Line 47  of the projects will be named with the c
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.
# Line 75  The reason for this model is twofold: Line 83  The reason for this model is twofold:
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,
# Line 121  you can omit it to use the fully qualifi Line 137  you can omit it to use the fully qualifi
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  ---------  ---------
# Line 137  To really use arch, you need to make loc Line 162  To really use arch, you need to make loc
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
# Line 174  Commit the change:: Line 200  Commit the change::
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
# Line 189  and then send that to tjl for incorporat Line 261  and then send that to tjl for incorporat
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
# Line 228  Initial Patch policy Line 290  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

Legend:
Removed from v.1.5  
changed lines
  Added in v.1.6

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26