SVN repo usage for trunk and release development

SPECIAL NOTE: YOU SHOULD BE USING SVN CLIENT VERSION 1.5 OR NEWER

alastor1{miller86}520: svn --version
svn, version 1.6.11 (r934486)
   compiled Jan 26 2011, 10:20:05

We re-organized the ITAPS repo and put all ITAPS-managed software under the software directory with a trio of sub-directories; trunk, tags and branches. We did this to help manage releases of ITAPS software. Here's a short primer on how releases are managed.

Because of this organization, you should only ever need to worry about the activities described below for the software part of the ITAPS repo.

Code freeze target and release target dates

We decide what features we want in the release and when we want to have completed those features so that we can choose a release.

Using our current release as an example, a little while ago, we decided we wanted to have the following new features in the release...
  • setAdjTable
  • generic data set/get functions to use void* rather than char*
  • some typedefs moved from iMesh to iBase
  • all implementations to be passing save-load of iMesh_unitTest.C.

Ok, so that sort of defined what would be in the release.

Then, we picked a date by which we all agreed to have all these features working in our respective implementations as well as tests for these features. We decided March 11 but delayed that again one week to March 18. That sets the release date.Typically, we also need to decide upon a code freeze date prior to the release date.

Making a release is rarely if ever an instantaneous thing. It can take days and sometimes even a couple of weeks depending on a vareity of factors. Because of this, it is necessary to freeze the code from anything new so that we can focus our work on fixing only existing things that are broken. The code freeze date is the date we decide that no more new development will go into the planned release. Note, new development here means stuff that is new (e.g. a new function in the iMesh API for example). New development does not include bug fix work necessary to fix any existing parts of a release.

I am speculating here but based on past experience with ITAPS software, I think our project requires a 1-2 week freeze period given the logistics involved in hearding the cats and bringing the planets into alignment. So, using our current release as an example, we choose March 11 as the code freeze date.

A potential problem with long code freezes is that it can prevent anyone from committing new work on the trunk. You don't want any new work getting in the way of finishing the release. To avoid this, we create a branch for the release called a release candidate. By creating a branch, we bifurcate development into two parallel branches, one for the upcomming release and one for continued new development that will go into future releases.

Between freeze and release completion there are TWO BRANCHES to manage

Between the code freeze date and the release date, we all agree that the only work we will do on the release is to fix bugs related to finishing the release. That means that any svn commits on the release candidate will be only to fix bugs in the release candidate.

New work can proceed normally on the trunk.

So, between freeze and release completion, as a developer, you have two branches to be worried about; the release candidate branch and the trunk. When you do work, you need to be sure you are doing it in the right place.

Release Candidate Development

A release candidate (RC) is a version of the software we think is ready for release. However, the first time we cut a release, we more than likely will find problems with it. So, we call it a candidate rather than an actual release.

We cut the first release candidate on the code freeze date and prior to our release target date by creating a new branch...

$ svn copy -m 'making 1.2 release candidate' \
    https://redmine.scorec.rpi.edu/svn/itaps/software/trunk \
    https://redmine.scorec.rpi.edu/svn/itaps/software/branches/1.2RC

This only needs to be done once, by whoever is marshaling the release (e.g. the release manager).

Any developer, in order to do work on the release candidate, needs to check it out (just like you would the trunk)...

$ svn co https://redmine.scorec.rpi.edu/svn/itaps/software/branches/1.2RC

This will create a directory named 1.2RC in the current working directory where you issued the command. Do whatever work you need on the release candidate and then commit your changes back to the release candidate (as you would on the trunk)...
$ cd 1.2RC
$ <do a bunch of bug fix work>
$ svn commit -m 'fixing bug in iMesh_unitTest regarding setAdjTable test'

Now, here's the tricky part. Your bug fix has only been committed to the RC branch. It will be in the current release but it is not on the trunk and therefore will not be in any future release.

In order to ensure that your bug fix work makes it back to the trunk, you need to merge the RC branch to the trunk. To do this, you need a (updated) working copy of the trunk which presumably you already have and are used to keeping up to date. So, from the top of your trunk working copy...

$ cd trunk
$ svn update # make sure you have most up to date trunk
$ svn merge https://redmine.scorec.rpi.edu/svn/itaps/software/branches/1.2RC
$ svn diff # take a look at the diffs and see if they are what you expect
$ svn commit -m 'merging my 1.2RC fixes to trunk'

Failing to merge RC to trunk

If you fail to merge your changes from RC to trunk, then any other developer doing work on the RC is going to run into your changes when s/he does a merge of their own RC work to the trunk. More than likely s/he will be completely caught off guard by files s/he didn't directly change in the RC getting merged when merging the RC to trunk and not know the correct action to take. So, always merge your RC change to trunk and commit them.

Work you want ONLY on RC

Note that if you do work on the RC that you do not want to make it back to the trunk (for example it might pertain to a feature being removed in future releases), then you still need to let the SVN repo know that that is your intention by doing a merge of the RC (with your changes) to your working copy of the trunk. Then, revert any changes resulting from the merge of the RC to your working copy of trunk. This lets SVN know that that change will only ever appear on the RC. It also prevents other developers from running into your RC-only work when they do a merge of RC to trunk and then accidentally merging your RC-only fixes to trunk.

Trunk Development

Trunk development proceeds normally.

Checking out specifc parts of the repository

The top level of the SVN project includes the following four directories...

$ svn ls https://redmine.scorec.rpi.edu/svn/itaps
docs/
older/
software/
www/

We decided to place the conventional trunk/branches/tags trio of dirs below the root of the project, underneath the software dir tree...
$ svn ls https://redmine.scorec.rpi.edu/svn/itaps/software
branches/
tags/
trunk/

A consequence1 of this is that if you checkout the root of the project like so...
svn co https://redmine.scorec.rpi.edu/svn/itaps

you will wind up getting not only the docs, older and www dir trees but also the software dir tree including, underneath it, the trunk, all releases and release candidates and all tags! In addition, when they are checked out, the resulting dir trees will be fully expanded (e.g. not efficiently stored as they are on the server where a file that is the same in multiple trees is not stored multiple times but instead shared).

To avoid this, if you want to check out only the trunk, do this...

    svn co https://redmine.scorec.rpi.edu/svn/itaps/software/trunk

If you want to check out a particular release, do this...
    svn co https://redmine.scorec.rpi.edu/svn/itaps/software/tags/<VERSION>

If you want to checkout a particular release candidate, do this...
   svn co https://redmine.scorec.rpi.edu/svn/itaps/software/branches/<RCVERSION>

If you want to checkout only the docs dir, do this...
    svn co https://redmine.scorec.rpi.edu/svn/itaps/docs

If you want to checkout only the www dir, do this...
    svn co https://redmine.scorec.rpi.edu/svn/itaps/www

You should probably never do this...
   svn co https://redmine.scorec.rpi.edu/svn/itaps

As per standard convention in the use of SVN, the branches and tags dirs contain nothing more than copies of the trunk tree at different stages in development (on the server, these copies are efficient in that files that are identical between copies are not actually stored multiple times but shared). In particular, no one should ever commit changes to a tag. And, after a release, unless more bug fix releases are going to be made to a given release, no one should commit changes to a previous release candidate.

1 In truth, this behavior is not really specific to ITAPS' use of SVN, for any project if you check out from the root, more than likely that will include the branches, tags and trunk dir trees.