From f04b0d448ab8fa1f2282b54753732ff6ccd81595 Mon Sep 17 00:00:00 2001 From: "Jonathan E. Guyer" Date: Fri, 5 Nov 2004 20:23:18 +0000 Subject: [PATCH] Actual CVS documentation. git-svn-id: svn+ssh://code.matforge.org/fipy/trunk@978 d80e17d7-ff13-0410-a124-85740d801063 --- documentation/CVS.txt | 68 +++++++++++++++++++ documentation/CVSadmin.txt | 136 +++++++++++++++++++++++++++++++++++++ 2 files changed, 204 insertions(+) create mode 100644 documentation/CVS.txt create mode 100644 documentation/CVSadmin.txt diff --git a/documentation/CVS.txt b/documentation/CVS.txt new file mode 100644 index 0000000000..48c59db5f1 --- /dev/null +++ b/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 ```` can be +obtained with:: + + $ cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/fipy checkout -r fipy + +An existing CVS checkout of |FiPy| can be shifted to a different state of +development by issuing the command:: + + $ cvs update -r + +.. |FiPy| replace:: FiPy diff --git a/documentation/CVSadmin.txt b/documentation/CVSadmin.txt new file mode 100644 index 0000000000..72115d7825 --- /dev/null +++ b/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. + +