[ff-cvs] fenfire/docs/pegboard/cvs_to_tla--tjl peg.rst

[Tuomas J. Lukka]

CVSROOT:        /cvsroot/fenfire
Module name:    fenfire
Branch:         
Changes by:     Tuomas J. Lukka <address@hidden>        03/09/12 04:38:06

Modified files:
        docs/pegboard/cvs_to_tla--tjl: peg.rst 

Log message:
        Current

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/fenfire/fenfire/docs/pegboard/cvs_to_tla--tjl/peg.rst.diff?tr1=1.5&tr2=1.6&r1=text&r2=text

Patches:
Index: fenfire/docs/pegboard/cvs_to_tla--tjl/peg.rst
diff -u fenfire/docs/pegboard/cvs_to_tla--tjl/peg.rst:1.5 
fenfire/docs/pegboard/cvs_to_tla--tjl/peg.rst:1.6
--- fenfire/docs/pegboard/cvs_to_tla--tjl/peg.rst:1.5   Thu Sep 11 13:26:08 2003
+++ fenfire/docs/pegboard/cvs_to_tla--tjl/peg.rst       Fri Sep 12 04:38:06 2003
@@ -3,19 +3,15 @@
 =============================================================
 
 :Author:   Tuomas J. Lukka
-:Last-Modified: $Date: 2003/09/11 17:26:08 $
-:Revision: $Revision: 1.5 $
-:Status:   Incomplete
+:Status:   Current
 
 Having the FenPDF prototype in production use requires more
 stability than we've needed so far. CVS is not good for
 branching and inspection of commits *before* allowing
 them into the official tree.
 
-I propose we move to arch, at the latest
-the moment version 1.1 (with star-merge)
-is finished, and start testing the 1.1 pre versions
-right away.
+I propose we move to arch.
+
 
 Issues
 ======
@@ -25,7 +21,12 @@
 Changes
 =======
 
+(to be moved to docs/ upon acceptance)
+
 The fenfire projects will be moved out of CVS and into arch.
+CVS commits will be disabled except for project managers: mirroring
+the arch trees to CVS is desirable.
+
 The arch categories 
 of the projects will be named with the current CVS directory names::
 
@@ -35,9 +36,7 @@
     callgl
     controllers
     fenfire
-    fenfire-cvs
     fenfire-depends
-    fenfire-priv
     libvob
     libvob-depends
     loom
@@ -48,12 +47,21 @@
     storm
     storm-depends
 
-Each project will have two official
-branches: ``devel`` and ``semistable`` (later, a ``stable`` branch
-may be added). 
+The official fenfire archive
+----------------------------
+
+The official fenfire archive will be named ::
+
+    address@hidden
+
+initially located in Himalia. It shall be made accessible through http
+as well as sftp.
+
+In it, each subproject will have a single mainline branch: ``dev``,
+with other branches (e.g. ``testing``, ``stable``) to be added later.
 
 The greatest change from the previous development model
-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**.
 
 This is not as bad as it sounds, as arch allows mutual merges
 and other branches between developers, so this is not limiting in any way.
@@ -75,44 +83,52 @@
    that the maintainer will actually read the code and accept
    or reject it (explaining why and what needs to be done for acceptance).
 
+The developers should have their own arch trees mirrored to himalia for easy 
merge
+by the project manager.
+
+Arch versions
+=============
+
+We need star-merge. 
+Tla 1.1 is not yet released.
+
+Because of this, you need to get tla-1.1pre5 (or later) and compile it
+for yourself.
+
 Examples
 ========
 
 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 
-================================================================
 
 Getting the official version
 ----------------------------
 
-In the following, I'll use the test archive address@hidden
-and address@hidden as the local archive. Adjust accordingly.
+In the following, I'll use address@hidden as the local archive and 
``/home/me/{archives}`` as
+your local archive dir. Adjust accordingly.
 
 First, register the location of the archive you are mirroring from::
 
-    tla register-archive address@hidden sftp://kuu/BIG/arch/test2arch
+    tla register-archive address@hidden 
sftp://himalia.it.jyu.fi/home/lukka/{archives}/address@hidden
 
-Then, create the local mirror::
+Then, create the local mirror to your own hard drive.
+You *could* use it directly but it's *safer* if we have lots of distributed
+mirrors::
 
-    tla make-archive --mirror-from address@hidden /BIG/arch/kuumirror
+    tla make-archive --mirror-from address@hidden 
/home/me/{archives}/address@hidden
 
 And finally, mirror the archive::
 
-    tla archive-mirror  address@hidden
+    tla archive-mirror address@hidden
+
+The last command is what you'll repeat to get the latest changes to your 
mirror.
 
-The last command is what you'll repeat to get the latest changes.
 
-**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
 you then need to clean up properly. Not fun.
 
 Next, get the official version of the full fenfire tree from the archive::
 
-    tla get address@hidden/ff--kuu--0.1 ff
+    tla get address@hidden/ff--dev--0.1 ff
 
 The name `ff` is the "full fenfire", i.e. all project trees of the subprojects,
 plus dependencies. The second argument is the directory name to use for the 
tree,
@@ -121,14 +137,23 @@
 The `ff` tree is an ``arch`` config, i.e. they are not automatically
 obtained but ::
 
-    tla buildcfg devel
+    tla buildcfg ff--dev--0.1
 
-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
+as the branch only by choice - see ``tla`` documentation about configs.
 
 **IMPORTANT**: DO NOT RUN BUILDCFG TWICE OR AFTER YOU MAKE CHANGES. It copies 
files
 that are "on the way" to save directories and recovering is not fun.
 
-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
+just as well check out all subprojects yourself.
+
+Now: the buildcfg tree is just the official version - you can't really *do* 
anything
+with it except build and run (remember symlinks for fenfire-priv and tmpimg).
+You should not edit it - that would be misusing arch badly.
+You need local branches for that.
+
+Note in the ``ff`` directory there is the ``DIRS`` file for easy foreach loops.
 
 Branching
 ---------
@@ -137,19 +162,20 @@
 and submit your changes back to the official tree.
 First, create the local archive::
 
-    tla make-archive address@hidden /home/me/archives/2003
+    tla make-archive address@hidden /home/me/{archives}/address@hidden
 
 **IMPORTANT**: address@hidden **MUST** be unique.
+
 Set it as your default archive::
 
     tla my-default-archive address@hidden
 
 Next, create local categories for any of the trees you intend to modify.
+Let's say you don't think you'll be editing anything except fenfire 
+(you can add more later)
 
     tla archive-setup fenfire--bar--0.1
 
-Note in the ``ff`` directory there is the ``DIRS`` file for easy foreach loops.
-
 Now, create the branch by tagging from the official revision::
 
     tla tag address@hidden/fenfire--kuu--0.1 fenfire--bar--0.1
@@ -174,6 +200,52 @@
 This commit created the version ``fenfire--bar--0.1--patch-1`` from the base
 version ``fenfire--bar--0.1--base-0``.
 
+Submitting changes
+------------------
+
+There are several ways to submit it to the maintainer. The simplest (for people
+with accounts on himalia) is to mirror your local archive to himalia::
+
+    tla make-archive --mirror address@hidden 
sftp://himalia.it.jyu.fi/home/me/{archives}/address@hidden
+
+(it's important to have it in the ``{archives}`` subdir so that the irc 
archbot 
+knows it's an archive) and then (everytime you've made a change)::
+
+    tla archive-mirror address@hidden
+
+mirrors the changes.
+
+Then you just inform the maintainer with a merge request::
+
+    Could you merge
+
+    address@hidden
+    sftp://himalia.it.jyu.fi/home/me/{archives}/address@hidden
+    fenfire--bar--0.1--patch-1
+
+and then things can go several ways: 1) the maintainer accepts and merges
+2) the maintainer rejects, saying "we don't want this change" or 
+3) the maintainer boomerangs it back: "yes, I'll accept but change it like X 
and Y first".
+
+In the first case, you don't need to do anything.
+In the second case, you should undo the patch in your local branch by ``tla 
replay --reverse``.
+In the third case, things get interesting, especially if you have other patches
+after that in your archive. The project manager will want to have small, easy 
changes
+to be easily able to judge them so you *shouldn't* just make the change and 
send the latest
+version! What you should do is to make a new branch for it:
+
+    tla tag address@hidden/fenfire--kuu--0.1 fenfire--bar-pegpatch1--0.1
+
+and then replay that exact patch to this branch and make the changes and send 
a merge
+request for this branch.
+
+If you're making a major change you think will have issues, you are probably 
best off *starting*
+with a new branch (that's what Tjl did in the Functional branch example).
+
+
+If you don't have access to himalia, you can still submit patches using 
changesets
+(or by publishing your archive through http elsewhere, of course).
+
 Now, let's get this patch as something we can send to the maintainer::
 
     tla get-patch fenfire--bar--0.1--patch-1
@@ -189,35 +261,25 @@
 This is an ideal case, where the patchset was directly what was wanted.
 However, in most cases, the command ``tla mkpatch`` should be used.
 
-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.
 
-- Boomerang (Finnish university term): you need to do some more work,
-  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.
+Merging changes from the main branch
+------------------------------------
 
-- Reject completely: this patch is not something the maintainer wants.
+After you have made changes to your local branch, and the maintainer has 
accepted
+other peoples' patches to the main branch, you need to synch up your local 
tree.
+The ``star-merge`` command is an excellent tool for this ::
 
-How do you cope when some patches are accepted, some rejected?
+    tla commit -L"Some changes"  # Make sure you have committed things exactly
+    tla update --in-place .      # If you're using more than one checkout, 
make sure
+                                   you're up to date
 
-The first rule of this is:
+    tla star-merge address@hidden/fenfire--dev--0.1 .
 
-    **It's your problem**.
+Make note of all 'C' messages and do ::
 
-With arch, you **can** solve the problem, but still: the maintainer will
-have no qualms making any decision even when it's guaranteed to make your
-tree messy.
+    find . -name '*.rej'
 
+afterwards to make sure nothing went wrong.
 
 
 Initial Patch policy
@@ -228,8 +290,8 @@
 The initial policy (at least of Tjl) is:
 
 - accept changes to Storm only from Benja
-- accept changes to Navidoc only from humppake
-- accept changes to CallGL only from Jvk
+- accept changes to Navidoc only from humppake (except for the data structure 
parts
+  which need to be moved out)
 
 - accept any changes to ``lava/`` dirs
 - accept any documentation / formatting cleanups if they are certain