[ff-cvs] fenfire ./Makefile docs/pegboard/cvs_to_tla--tj...

[Tuomas J. Lukka]

CVSROOT:        /cvsroot/fenfire
Module name:    fenfire
Branch:         
Changes by:     Tuomas J. Lukka <address@hidden>        03/09/03 07:19:15

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

Log message:
        patch-1
        Start functional peg
        patch-2
        Issuesforpeg
        patch-3
        Mergefromjousi
        patch-1
        Added a step-by-step explanations to cvs_to_tla PEG
        patch-2
        more

CVSWeb URLs:
http://savannah.gnu.org/cgi-bin/viewcvs/fenfire/fenfire/Makefile.diff?tr1=1.44&tr2=1.45&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/fenfire/fenfire/docs/pegboard/cvs_to_tla--tjl/peg.rst.diff?tr1=1.3&tr2=1.4&r1=text&r2=text
http://savannah.gnu.org/cgi-bin/viewcvs/fenfire/fenfire/docs/pegboard/functional_futureproof_api--tjl/peg.rst?rev=1.1

Patches:
Index: fenfire/Makefile
diff -u fenfire/Makefile:1.44 fenfire/Makefile:1.45
--- fenfire/Makefile:1.44       Thu Aug 28 10:23:18 2003
+++ fenfire/Makefile    Wed Sep  3 07:19:14 2003
@@ -146,6 +146,9 @@
        if [ -f "../TAGS" ]; then rm ../TAGS; fi
        cd .. && find fenfire libvob alph callgl glmosaictext alph storm 
navidoc -type d -name CVS -exec sed -e '/^[^/]/d' -e 's:^\(/[^/]*\).*:{}\1:' -e 
's:/CVS/:/:' {}/Entries \;|xargs etags --append
 
+tags:
+       ctags -R metacode docs lava org
+       
 
 ##################
 # Storm pool rsync
Index: fenfire/docs/pegboard/cvs_to_tla--tjl/peg.rst
diff -u fenfire/docs/pegboard/cvs_to_tla--tjl/peg.rst:1.3 
fenfire/docs/pegboard/cvs_to_tla--tjl/peg.rst:1.4
--- fenfire/docs/pegboard/cvs_to_tla--tjl/peg.rst:1.3   Sun Aug 31 08:28:05 2003
+++ fenfire/docs/pegboard/cvs_to_tla--tjl/peg.rst       Wed Sep  3 07:19:14 2003
@@ -3,8 +3,8 @@
 =============================================================
 
 :Author:   Tuomas J. Lukka
-:Last-Modified: $Date: 2003/08/31 12:28:05 $
-:Revision: $Revision: 1.3 $
+:Last-Modified: $Date: 2003/09/03 11:19:14 $
+:Revision: $Revision: 1.4 $
 :Status:   Incomplete
 
 Having the FenPDF prototype in production use requires more
@@ -20,6 +20,8 @@
 Issues
 ======
 
+- Do humppake and Benja and jvk want to run their own official trees?
+
 Changes
 =======
 
@@ -77,6 +79,165 @@
 ========
 
 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.
+
+First, register the location of the archive you are mirroring from::
+
+    tla register-archive address@hidden sftp://kuu/BIG/arch/test2arch
+
+Then, create the local mirror::
+
+    tla make-archive --mirror-from address@hidden /BIG/arch/kuumirror
+
+And finally, mirror the archive::
+
+    tla archive-mirror  address@hidden
+
+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
+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
+
+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,
+you can omit it to use the fully qualified name or give your own.
+
+The `ff` tree is an ``arch`` config, i.e. they are not automatically
+obtained but ::
+
+    tla buildcfg devel
+
+will get them for you. Make sure you have enough disk space.
+
+**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.
+
+Branching
+---------
+
+To really use arch, you need to make local branches from the official source
+and submit your changes back to the official tree.
+First, create the local archive::
+
+    tla make-archive address@hidden /home/me/archives/2003
+
+**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.
+
+    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
+
+This should create the first revision of the ``fenfire--bar--0.1`` branch.
+Now, remove the fenfire directory from ``ff/`` and get a new one::
+
+    rm -rf fenfire          # XXX Careful!!
+    tla get fenfire--bar--0.1 fenfire
+
+Now you have your own modifiable copy in the fenfire dir.
+
+Now, there are LOTS of variations. You could have created your own config,
+etc. Read the arch docs for all that. Now, we'll make the first change
+to the local fenfire tree (self-referentially, that'll be the inclusion of this
+text in the cvs_to_tla PEG -- I'm testing these commands as we speak).
+
+Commit the change::
+
+    tla commit -L"Added a step-by-step explanations to cvs_to_tla PEG"
+
+This commit created the version ``fenfire--bar--0.1--patch-1`` from the base
+version ``fenfire--bar--0.1--base-0``.
+
+Now, let's get this patch as something we can send to the maintainer::
+
+    tla get-patch fenfire--bar--0.1--patch-1
+
+This creates the directory ``fenfire--bar--0.1--patch-1.patches``. We can look
+at what it contains::
+
+    tla show-changeset fenfire--bar--0.1--patch-1.patches
+    tla show-changeset --diffs fenfire--bar--0.1--patch-1.patches
+
+and then send that to tjl for incorporation in the mainline source.
+
+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.
+
+- Reject completely: this patch is not something the maintainer wants.
+
+How do you cope when some patches are accepted, some rejected?
+
+The first rule of this is:
+
+    **It's your problem**.
+
+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.
+
+
+
+Initial Patch policy
+--------------------
+
+(This will certainly need revision and further PEGs to settle completely).
+
+The initial policy (at least of Tjl) is:
+
+- accept changes to Storm only from Benja
+- accept changes to Alph only from humppake
+- accept changes to CallGL only from Jvk
 
+- accept any changes to ``lava/`` dirs
+- accept any documentation / formatting cleanups if they are certain 
+  to be in the right direction
+- reject unpegged changes to frozen interfaces or classes if a PEG has
+  not been made, unless there are really dire circumstances. These 
+  classes will each be marked with the word "Frozen".
 
+- in all other cases (as well as the above ones, occasionally), use 
+  my best judgement