Purpose

Tag (i.e., call cvs rtag on) a package with a tag of SCons-acceptable form.  Update the package's SConscript  and release.notes files before tagging.

Syntax

The command is "stag", short for "SCons tagger". It (release 0.2.5) may be invoked

stag -help

or

stag  -cvspath= path-relative-to-cvsroot -notes=" text-for-release.notes" (-major | -minor | -patch | -custom= custom-version-string) [-S ] [-branch= alternate-branch]  [-verbose]

Value of -cvspath determines package name: it's the last component of the path. Value of -branch defaults to MAIN.  If -branch is specified and is anything other than MAIN, -custom must be used and its value must follow the form for tags along a branch, namely  dd-dd-dd-aadd where all the d's are digits and the a's are alphabetic characters, e.g. 01-02-00-gr01.  If -custom is specified for a  main branch tag its value must be of the form dd-dd-dd. -verbose may add some informational messages to terminal output.  The -S flag should be used when (and only when) tagging the package SConsfiles.

Examples

//simplest example.  Just tag a pkg
stag -notes="Some comments" -patch -cvspath=xmlBase

//tag pkg which happens to be contained in another pkg
stag -notes="Tagging a subpackage" -minor -cvspath=celestialSources/GRB

//tag pkg which contains children (GRB, etc.). Doesn't tag the children
stag -notes="Tagging parent" -minor -cvspath=celestialSources

//tag along a branch
stag -notes="Tagging along a branch" -branch=GlastRelease-15-49-02 custom=05-04-11-gr01 -cvspath=xmlBase

Where to find it

stag is best used on a central SLAC machine.  On rhel5 and rhel6 machines, it may be found at

 /afs/slac.stanford.edu/g/glast/applications/install/@sys/usr/bin/stag

What will happen

In case one of -major, -minor or -patch has been specified, stag will generate the new version string by looking up the "highest" tag along the main branch, incrementing the specified field and zeroing fields to the right, if any, and finally prepending with the package name derived from the value of -cvspath. In the case of a custom string, stag merely prepends the package name.

stag will then check out the package into a temp directory (along branch if so specified), update the version string in the package's SConscript file, and add a suitable line to release.notes. A release.notes file which has been modified by stag will have lines with format

    full-version-string date username comment 

like this: 

GoGui-00-08-07 26-Nov-2008    jrb Support exclude; more informative base inst. display

The complete file looks like this:

** @file release.notes
 * Package GoGui
 * Coordinator: Joanne Bogart
 *
 *                  EOH

 GoGui-00-09-00 05-Dec-2008    jrb Support for supersede directory
 GoGui-00-08-08 01-Dec-2008    jrb Add msg tab for debug info, warnings
    Add edit-file function
 GoGui-00-08-07 26-Nov-2008    jrb Support exclude; more informative base inst. display
 GoGui-00-08-06  25-Nov-2008  jrb Fix for blank-slate use.

If, as in the above case, release.notes has a line containing the toke EOH, stag will insert the new line just below it.  Otherwise the new line will go at the end of the file.

If the package has subpackages, like celestialSources, the new tag will only be applied to the files belonging to the specified package, not to files belonging to children.

Prerequisites to run

User must have a working cvs client, invoked with the command cvs. stag will try to determine repository from the environment variable CVSROOT; if not set stag will fall back on default value :ext:centaurusa.slac.stanford.edu:/nfs/slac/g/glast/ground/cvs. Similarly it will attempt to determine protocol from the environment variable CVS_RSH; if not set it will use ssh.

Prerequisites to tag a package

The package must have a file called SConscript which includes "# Authors:" and "# Version:" lines (filled with appropriate values).  See the SConscript file for package irfs for a minimal example.  The package must also have a doc directory containing a file release.notes. For the first tag of a package the  -custom= custom-version-string must be used (usually with custom-version-string=00-00-00).

Status 

An executable of the most current version, 0.2.5,  can be found below ftp://ftp-glast.slac.stanford.edu/glast.u05/stag. That RHEL5 build will also run on RHEL6.

Windows users please note

The most recent version available for Windows is 0.2.4. You will also need to download the libraries mingw10.dll and qtcored4.dll if you don't already have them. They can be found at ftp://ftp-glast.slac.stanford.edu/glast.u05/GoGui/. Select the file QtForGoGui.zip.  However, we don't recommend tagging remotely.

Tagging along a branch has not been tested worked properly in one test case.

  • No labels