Fops,
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:1.44.2.11
Repository revision: 1.44.2.11 /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: 1.44.2.8)
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
Junk2.class:
$Header: /home/pbw/src/java/RCS/Junk2.java,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
