Some more comments on ways of using CVS tags.

At present, we are using the trunk for ongoing development.  We have a 
*branch*, fop-0_20_2-maintain, and a release tag, fop-0_20_3.  Branch 
tags name a branch off the trunk (or off another branch.)  Every version 
of every file on a branch will be tagged with the branch tag.  Release 
tags name one particular revision of each file in the tagged release 
set, so only one possible version of each file can be associated with a 
release tag.  As it happens, the versions tagged with the release tag 
fop-0_20_3 are on the tagged branch fop-0_20_2-maintain.

Issuing 'cvs status -v build.xml' at the xml-fop module level of a tree 
checked out with "-r fop-0_20_2-maintain" shows (inter alia)

   Working revision:
   Repository revision:       /home/cvspublic/xml-fop/build.xml,v
   Sticky Tag:          fop-0_20_2-maintain (branch: 1.44.2)

   Existing Tags:
        fop-0_20_3                      (revision:
        fop-0_20_2-maintain             (branch: 1.44.2)
        fop-0_20_0                      (revision: 1.37)

I.e., the development in the fop-0_20_2-maintain branch includes the 
fop-0_20_3 release.

The macro text associated with the *particular*, or release, tag of a 
file is "$Name".  Files checked out using the "-r fop-0_20_3" tag will 
have the text "$Name$" (or any previous expansion of that text) replaced 
with the text "$Name: fop-0_20_3 $" when checked out.  This is 
reasonable because only that version of that file is associated with 
that tag.  On the other hand, files checked out using "-r 
fop-0_20_3-maintain" will have "$Name" (or any previous expansion of the 
text) set to "$Name:  $", because the branch tag may be applied to any 
version of the file existing in the branch.

There are, of course, implications in this for CVS-derived version 
strings.  The only time that the $Name$ string will be visible is in a 
release.  All other versions, including ongoing development versions, 
will see "$Name:  $"  I don't consider this disadvantage to outweigh the 
advantages of a guaranteed association between the CVS tree and the 
version reported by formal releases.  To maximise these advantages, 
every class source file in the tree should have

public static final String header = "$Header$", tag = "$Name$";

Build information is then available in binary distributions through the 
 RCS ident command.  E.g.

java 16:20$ ident Junk2.class
     $Header: /home/pbw/src/java/RCS/,v 1.1 2002-04-25 
16:19:05+10 pbw Exp pbw $
     $Name:  $

In the case of formal releases, the occurrence of an empty $Name$ 
keyword indicates a failure of the build process.  The $Header$ keyword 
can then give some clues as to why.

***WARNING*** Jars and class files checked into CVS must have their '-k' 
flag defaulted to 'o' - original value at checkin - to prevent 
corruption of binary files.  I don't know whether this is critical for 
class files, but I would not treat them as binary files.

To construct a release, the set of committed files in the tree from 
which the release is being prepared will have to be tagged, as they are 
now, by cvs tag, or possibly by cvs rtag.  This set of files will then 
have to be extracted with 'cvs checkout -r TAG' in order to ensure that 
the $Name$ keyword is expanded with the release tag.  Release builds 
would be prepared from this tree.

A side-effect of this will be that the source tree of the release will 
have a sticky tag; the release tag.  If this tree were left in place, 
and maintenance attempted within it, any attempt to commit changes would 
fail because of the sticky tag, because it refers only to one particular 
version of each file.  E.g., if a release of FOP_Release_0-20-4Final 
were made, and some fixes applied in the same tree, a commit would fail with

cvs commit: sticky tag `FOP_Release_0-20-4Final' for file `whatever' is 
not a branch
cvs [commit aborted]: correct above errors first!

To properly maintain this release, a branch tag should be created from 
the tree.

$ rtag  -b  -r  FOP_Release_0-20-4Final   FOP_0-20-4_maint   xml-fop

then, at the top of the release tree,

$ cvs checkout  -r FOP_0-20-4_maint

To the best of my knowledge, the new branch tag will become sticky, 
overwriting the previous release tag.

What about the empty $Name$ keyword in the development branch, i.e. the 
trunk?  It doesn't really matter for development.  Once the process is 
tested and trusted, the absence of a $Name$ keyword is nto crucial.  In 
any case, a special moving tag could be used to test on the trunk. 
 Assign, say, FOP_0-10-0_Dummy as a testing tag.  Then, to test the 
trunk with a valid $Name$ keyword,

$ cvs -d root-value rtag -F -r HEAD FOP_0-10-0_Dummy xml-fop

This assigns the release tag FOP_0-10-0_Dummy to the current HEAD 
versions.  The -F flag will move the tag if it exists, e.g., from a 
previous test.  Note that the $Name$ keyword will not be set in any of 
the existing checkouts (unless previously used).  In a clean directory,

cvs -d root-value checkout -r FOP_0-10-0_Dummy xml-fop

This will checkout the same files as the current HEAD (provided no-one 
is updating the trunk while this is going on), but with a sticky tag of 
FOP_0-10-0_Dummy.  Furthermore, the $Name$ keyword will have been 
expanded to $Name: FOP_0-10-0_Dummy $, so testing of the version 
funtionality at the HEAD can be pursued.  There are two possibilities 
now for the future of this new tree.  You can release and delete the tree.

$ cd dir-above-the-module-dir
$ cvs -d root-value release -d xml-fop
Answer the dialog an the tree will be deleted.  Alternatively,

$ cd module-dir
$ cvs -d root-value update -A

This will remove the tree's sticky FOP_0-10-0_Dummy tag, restoring it to 
a HEAD tree, but with the useful side-effect of leaving the previously 
expanded $Name$ keyword intact.  This value will remain set on each 
individual file until a commit is performed, or until a commit occurs in 
another HEAD tree, and an update is performed in this tree.

All in all, it looks promising for the use of $Name$ in the xml-fop module.


To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]

Reply via email to