Archived: CVS Branches in GLAST Offline Software

Tag names for GlastRelease, ScienceTools, and EngineeringModel checkout packages follow the CMT format where the three numbers are prefaced by v, r, and p (for version, revision and patch). If there is a patch number, it indicates that one of the constituent packages has been branched.

Note: Tag names for GlastRelease, ScienceTools, and EngineeringModel releases are spelled out and include the version number as in GlastRelease v2r0. Branch names are abbreviated (GR, ST, and EM) and include a hyphen before the version number, as in GR-v2r0. If a GlastRelease includes a patch number (e.g., GlastRelease v2r0p1), it means that one of the constituent packages in the release has been branched. (See example.)

Why Branch?

Branches provide an easy method of applying software patches to a released version of a package while allowing development to continue along the main trunk of that same package.  This enables users to obtain necessary patches without requiring them to pick up other, possibly untested, updates.  

Potential Pitfalls

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

Branch Naming

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:

GR-v4r5

Note the use of the dash between the name of GR and the tag.

Creating a new Branch

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

cvs rtag -b -r v4r3 GR-v4r5 TkrRecon

Notes:

• We are branching off of the v4r3 tag of TkrRecon, and we create a branch name of
  GR-v4r5. 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.

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-v4r5 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:

[package tag]gr#  or [package tag]em#

Example:

A developer branched off of the v3r2 tag of TkrRecon.

To apply the first tag along this branch, we would name it:

v3r2gr0

Where fixes applied have been based on the v3r2 tag of TkrRecon; these changes are meant for GlastRelease and this is the first tag. 

The next tag applied to this same branch would be named:

v3r2gr1

and so on....

Similarly if a branch tag is meant for EngineeringModel, we would tag it as:

v3r2em0

How to Tag on a Branch?

• Using CVS directly:

cvs rtag -r GR-v4r5 v4r3gr0 TkrRecon

where GR-v4r5 is the name of the branch to apply the tag to.  This command will tag the head of the GlastRelase-v4r5 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/v4r3
cvs tag v4r3gr0

Release Manager and Tagging

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

vN(rN)(pN)

Merging 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)

• Enter the package directory, for example:  TkrRecon/v3r2

• Perform a CVS merge at the command line:

  cvs update -jGlastRelease-v4r5

• 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.

References

Note from Traudl:

http://www-glast.stanford.edu/protected/mail/soft/2003/0160.html

Owned by: Heather Kelly