CVS Branches in GLAST Offline Software

Note: As of July 28, 2009, the Science Analysis Systems group moved from the CMT tagging convention to the SConscript convention. This means that CMT version ScienceTools-v9r15p2 now equates to SCons version ScienceTools-09-15-02.

SCons Tag Names

Tag names for GlastRelease and ScienceTools checkout packages now follow the new SCons format (packageName-xx-yy-zz); however, the CMT tags, where the three numbers are prefaced by v, r, and p (for version, revision and patch) are still applied automatically. Parallel CMT builds continue to be made, and many developers are still using the CMT tags for CMT builds. Hence, during this transition period, it is necessary to be familiar with both; especially for GlastRelease builds. ScienceTools are nearing the end of this transition.

Branch Naming

SCons tags along a branch are of the form:

<packageName>-xx-yy-zz-ab##

Note:  In response to tags applied in the new format, the existing CMT Release Manager will apply a CMT-style tag of the form vxxryypzzab##.  SCons branch names for GlastRelease and ScienceTools releases are of the form:

GlastRelease-01-02-13-br##

Potential Pitfalls

Changes along a branch are not applied to the main line of development.  This means, changes can be "lost" if they exist only on a branch.  Developers must be sure to merge changes from the branch back into the main trunk. (Refer below to: Merge a Branch back into the Main Trunk.)

CVS allows users to specify a name for the branches they create.  GLAST Offline will name branches according to the tag of GR they are associated with, for example:

GlastRelease-04-05-00-br##
(Note the use of the dash between the name of GR and the tag.)

The CMT RM will continue to apply CMT style branch names automatically for all subpackages of GR and ST. The form of these branch names is:

GlastRelease-virjpk

Creating a New Branch

You can create a new branch without having to check out a copy of the package:

cvs rtag -b -r TkrRecon-04-03-00 GlastRelease-04-05-00-br## TkrRecon

Notes:

We are branching of of the TkrRecon-04-03-00 tag of TkrRecon, and we create a branch name of GlastRelease-04-05-00-br##. The -b tells CVS to create the branch; -r tells it to root the branch at the revision corresponding to the tag.

You can also branch using a specific tag, date, or time. (See Guide to CVS commands.)

Accessing the Branch

The important thing to remember is that — if you want to develop along the branch — you must first checkout the code from the branch.  Developers who want to access the HEAD of a branch in order to make code update to the branch can do so:

Via MRvcmt by using the name of the branch as the tag:

OR..., by using CVS directly, where again we use the branch name as the tag:

cvs co -r GlastRelease-04-05-00-br## TkrRecon

Note: An easy way to double-check that the branch was accessed successfully is to view the contents of the CVS directories in your package.  Typically, there would be a Tag file containing the name of the branch you think you have retrieved from CVS.

Branch Tag Naming Convention

Usually, changes that occur along a branch must be tagged so that they can be used.  Tag names along a branch will take the following form:

<packageName>-xx-yy-zz-gr##

Example:

A developer branches off of the tag TkrRecon-03-02-00. To apply the first tag along this branch, we would name it:

TkrRecon-03-02-00-gr01

(Note: We are trying to move away from branch tags starting at zero in favor of starting at 1.)

where fixes applied have been based on theTkrRecon-03-02-00; these changes are meant for GlastRelease and this is the first tag. 

and so on....

How to Tag on a Branch

Using CVS directly:

cvs rtag -r GlastRelease-04-05-00-br## TkrRecon-04-03-00-gr01

where GlastRelease-04-05-00-br## is the name of the branch to apply the tag to.  This command will tag the head of the GlastRelease-04-05-00 branch.

OR

While working on a local copy of your package that is on a branch, you may use the CVS tag command by entering the package directory, such as:

cd TkrRecon-04-03-00-gr01
cvs tag TkrRecon-04-03-00-gr01

Release Manager and Tagging

Currently, the Release Manager (RM) will skip tags for LATEST that do not follow the form of:

<packageName>-xx-yy-zz

Merge a Branch Back into the Main Trunk

Typically, patches applied along a branch will ultimately be merged into the main trunk of the package.  This can be easily overlooked and developers should make sure to keep track of the branches on their packages.  When developers are ready to merge changes into the main trunk, they:

Checkout the HEAD of the package (along the main trunk)

1. Enter the package directory; for example:

   TkrRecon/TkrRecon-03-02-00

2. Perform a CVS merge at the command line:

   cvs update -jGlastRelease-branch-04-05-00
   

Quite likely there will be conflicts, which will be noted by CVS as it makes the update.  The CVS manual provides an example concerning handling conflicts:

http://ximbiot.com/cvs/wiki/index.php?title=CVS--Concurrent_Versions_System_v1.12.12.1

Once the conflicts are handled, the developer can check in their modifications back into the HEAD of the main trunk of the package.