Actual CVS documentation.

git-svn-id: svn+ssh://code.matforge.org/fipy/trunk@978 d80e17d7-ff13-0410-a124-85740d801063

documentation/CVS.txt

@@ -0,0 +1,68 @@
+---------
+CVS usage
+---------
+
+Most users will not want to download the latest state of |FiPy| in the CVS
+repository, as these files are subject to active development and may not
+behave as desired. Any released version of |FiPy| will be designated with
+a fixed tag:
+
+``version-x_y``
+    designates a released version x.y.
+
+    .. include:: VERSION.txt
+
+Most users will not be interested in particular version numbers, but
+instead with the degree of code stability.  Different "tracking tags" are
+used to indicate different stages of |FiPy| development.  You will need to
+decide on your own risk tolerance when deciding which stage of development
+to track.  The tracking tags applied |FiPy|, in decreasing order
+stability, are:
+
+``STABLE``
+    designates the most recent release in the repository that can be
+    considered stable for daily use by the common user.  This is a good tag
+    to track if you don't want to run into bugs introduced with ongoing
+    development but would like to take advantage of new features as soon as
+    possible.
+
+``CURRENT``
+    designates the most recent code on the trunk forming a coherent state
+    of |FiPy|, in general this will mean a release, but can also mean a
+    pre-release testing version.  For instance, the release engineer might
+    ask testers to test ``CURRENT`` before he makes a release.  This tracking
+    tag is restricted to the trunk.
+
+``HEAD``
+    this is a CVS internal tag designating the latest revision of any file
+    present in the repository.  It is also a valid branch tag designating
+    the trunk.  For our purposes ``HEAD`` can be used as a tracking tag
+    designating the very latest code checked into the repository; |FiPy| is
+    not guaranteed to pass its tests or to be in a consistent state when
+    checked out under this tag.  This tracking tag is restricted to the
+    trunk.
+
+One final type of tracking tag to note:
+
+``branch-version-x_y``
+    designates a line of development based on a previously released version
+    (i.e., if current development work is being spent on version 0.2, but a
+    bug is found and fixed in version 0.1, that fix will be tagged as
+    ``version-0_1_1``, and can be obtained from ``branch-version-0_1``).
+
+..
+
+Any other tags will not generally by of interest to most users.
+
+
+A fresh copy of |FiPy| that is designated by a particular ``<tag>`` can be
+obtained with::
+
+   $ cvs -z3 -d:pserver:[email protected]:/cvsroot/fipy checkout -r <tag> fipy
+
+An existing CVS checkout of |FiPy| can be shifted to a different state of
+development by issuing the command::
+
+   $ cvs update -r <tag>
+
+.. |FiPy| replace:: FiPy

documentation/CVSadmin.txt

@@ -0,0 +1,136 @@
+=============
+CVS practices
+=============
+
+HEAD
+
+    this is of course a CVS internal tag designating the latest revision of
+    any file present in the repository.  It is also a valid branch tag
+    designating the trunk.  For our purposes HEAD can be used as a tracking
+    tag designating the very latest code checked into the repository;
+    FiPy is not guaranteed to pass its test or to be in a consistent state
+    when checked out under this tag.  Obviously this tracking tag is
+    restricted to the trunk.
+
+CURRENT
+
+    designates the most recent code on the trunk forming a coherent state
+    of FiPy, in general this will mean a release, but can also mean a
+    pre-release testing version.  For instance, the release engineer might
+    ask testers to test CURRENT before he makes a release.  This tracking
+    tag is restricted to the trunk.
+
+STABLE
+
+    designates the most recent release in the repository that can be
+    considered stable for daily use by the common user.  This is a good tag
+    to track if you don't want to run into bugs introduced with ongoing
+    development but would like to take advantage of new features as soon as
+    possible.
+
+version-x_y
+
+branch-version-x_y
+
+branch-refactoring_etc
+
+--------
+Branches
+--------
+
+Break off for radical refactoring. *Starting on main trunk*::
+
+    $ cvs tag root-branch-refactoring_etc
+    $ cvs tag -b branch-refactoring_etc
+    $ cd ..
+    $ cvs co -r branch-refactoring_etc -d branch-refactoring_etc fipy
+    $ cd branch-refactoring_etc
+
+Edit and add to branch::
+
+    $ emacs ...
+    $ cvs ci -m "refactoring"
+    $ cvs tag refactoring_stage_A
+
+    $ emacs ...
+    $ cvs ci -m "more refactoring"
+    $ cvs tag refactoring_stage_B
+
+Merge developments from trunk::
+
+    $ cvs tag -r HEAD somePointOnTrunk
+    $ cvs up -j somePointOnTrunk
+    $ cvs ci -m "merged main trunk"
+    $ cvs tag merge-somePointOnTrunk_to_refactoring
+
+Refactoring complete::
+
+    $ cd ../trunk
+    $ cvs up -j branch-refactoring_etc
+    $ cvs ci -m "merged refactoring, etc."
+    $ cvs tag merge-refactoring_etc
+
+**Now cease all work on branch-refactoring_etc**
+
+--------
+Versions
+--------
+
+At point of version release x.y, *on main trunk*::
+
+    $ cvs tag version-x_y
+    $ cvs tag -F STABLE
+    $ cvs tag -F CURRENT
+
+---------
+Bug fixes
+---------
+
+At the point some fix is made to an old version n.m, *on main trunk*::
+
+    $ cvs tag -r version-n_m -b branch-version-n_m
+    $ cd ..
+    $ cvs co -r branch-version-n_m -d branch-version-n_m fipy
+    $ cd branch-version-n_m
+
+Fix the code::
+
+    $ cvs ci -m "fix n.m.q"
+    $ cvs tag version-n_m_q
+
+Possibly::
+
+    $ cvs tag -F STABLE
+
+Now merge n.m.q changes back to main trunk::
+
+    $ cd ../trunk
+    $ cvs up -j branch-version-n_m
+    $ cvs ci -m "merged n.m.q"
+    $ cvs tag merge-version-n_m_q
+
+Possibly::
+
+    $ cvs tag -F CURRENT
+
+Make new fix q+1 to n.m::
+
+    $ cd ../branch-version-n_m 
+
+Fix the code::
+
+    $ cvs ci -m "fix n.m.q+1"
+    $ cvs tag version-n_m_q+1
+
+Again, merge n.m.q+1 changes back to main trunk::
+
+    $ cd ../trunk
+    $ cvs up -j version-n_m_q -j branch-version-n_m
+    $ cvs ci -m "merged n.m.q+1"
+    $ cvs tag merge-version-n_m_q+1
+
+.. danger::
+
+   The double ``-j`` is very important to get right.
+
+