GENIE:Developers guide

Introduction
If you actively contribute source code to the project, then these pages are for you:) The essentials of getting the code, including a short intoduction to Subversion, and running the model are in the guide to running an experiment on your local machine.

The Checkout-Test-Commit Cycle
GENIE has contributers around the world. We all semi-automonously and have free range over the model code. For this reason, it is essential that we all ensure that our changes to the model to not break it, and cause trouble for someone else--remember it could be you one day!:) Also, as scientists, we need to ensure that the GENIE model is behaving correctly at all times.  Given all this it is vital that whenever we make a change to the code, we run the tests.

Branches and Tags
We typically commit small changes, that do not disrupt the model in general, to the HEAD. However, for larger projects, it is useful to be able to work on a branch from the main trunk. In this way, we can develop some new features with all the benefits of version control, but in the comfort of our own workspace. When our work on that facet of the model is complete, we can merge our changes back to the HEAD version.

Tags are snapshots of the repository, i.e. we don't do any development with a tag. They are useful for labelling the state of the model at a particular time, i.e. when we did such-and-such experiment, or wrote the paper blah. We normally take a snapshot at some stable point along the development of the model, give it a name and create a release.

Branches are tags are treated similarly by Subversion and so I will describe them together.

First, we must give our branch or tag a name. This name must not clash with one which has gone before. You can inspect which branches or tags are in the repository easily by typing:

svn list http://source.ggy.bris.ac.uk/subversion/genie/branches

or:

svn list http://source.ggy.bris.ac.uk/subversion/genie/tags

Now that we have a unique name, it's time to create our branch:

svn copy http://source.ggy.bris.ac.uk/subversion/genie/trunk http://source.ggy.bris.ac.uk/subversion/genie/branches/ -m "this is the reason why I'm branching"

or tag:

svn copy http://source.ggy.bris.ac.uk/subversion/genie/trunk http://source.ggy.bris.ac.uk/subversion/genie/tags/rel-X-Y-Z -m "these are the details for this tag"

Merging
After a while--but not too long--we will want to merge our branch back into onto the HEAD. (If our enterprise on the branch wasn't successful, we can just abandon it to the sands of time.) When considering merging, it will be useful to consider the concept of a changeset. This can be simply the package of changes that we made on our branch that we would like to incorporate into the trunk. Subversion gives a unique revision number to the state of the repository after each commit. Thus, in general terms a changeset may be the changes which occured between revisions revA and revB. (We'll see this the example below as, say -r :.)

OK, enough abstraction, let's create a concrete example. Let's say that your changes are on a branch called snowball. You will also need an upto date checkout of the trunk to hand, I'll assume this is in ~/genie:

cd ~/genie svn update

NB this next bit is important and perhaps unexpected. Now, we will need to determine the changeset for your branch--we don't want any of the changes before you branched:

svn log --verbose --stop-on-copy http://source.ggy.bris.ac.uk/subversion/genie/branches/snowball

You that you started your branch at revA and that the HEAD of your branch is revB. Now we have the changeset that we wish to merge:

svn merge -r revA:revB http://source.ggy.bris.ac.uk/subversion/genie/branches/sbowball -m "what I merged in changeset revA:revB"

NB It is important that you include the changeset in your comment as if you want to merge from your branch again at some point in the future, you will not want to merge this changeset again. (It is implit that you are merging from your brancg to your working copy of the trunk.) Now you must ensure that all is well--no conflicts, the tests run etc--and you may commit your merged changeset back to the repository trunk.

The merge command is very powerful and can be used to undo changes and resurrect old repository items among other things. Rather than repeat the text here, I'll refer you to the | Subversion book.