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 work semi-automonously and have free range over the model code. Therefore, it is essential that we all ensure that our changes do not break the model. A broken model will cause trouble for ourselves and others--remember it could be you one day, eager to run an experiment, but frustrated and baulked by some broken aspect of the model! Also, as scientists, we need to ensure that the GENIE model is behaving correctly at all times. To this end,

it is vital that whenever we make a change to the model, we run the tests.

Please, please, pretty-please document your code!:-)
Fortunately, this is very easy.


 * Just add comments to your code, following these conventions.
 * Add to this wiki.  How to edit the wiki.

Branches and Tags
We typically commit small changes, that do not disrupt the model in general, to the 'trunk of the repository. However, for larger tasks, it is useful to be able to work on a branch. In this way, we can develop some new features with all the benefits of version control, but in the comfort of our own workspace--our commits on a branch do not effect the trunk. When our work on a branch is complete, we can merge our changes back to the trunk. (Should we wish, we can also merge selected aspects of the trunk into our branch, as we work along. This is useful for keeping our branch up-to-date with any important happenings on the trunk and so head-off potential incompatabilities later on.)

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 such-and-such paper. 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 quickly and easily inspect the branches or tags in the repository 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

To create a branch, type the following, replacing  with the branch name of your choice:

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

or similarly, to create the tag rel-X-Y-Z (see the GENIE versions page for more information on tag naming conventions):

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 "The details for this tag are..."

Merging
After a while--but not too long--we will want to merge our branch back into onto the trunk. (If our enterprise on the branch wasn't successful, we can just abandon it to the sands of time.) When thinking about merging, it will be useful to consider the concept of a changeset. Subversion gives a unique revision number to the state of the repository after each commit. Minimally, a changeset comprises the changes made between one revision number and the next. More generally, a changeset is the changes which occured between revisions revA and revB. In foregoing context, a changeset may be all the changes you made on a branch which you now wish to merge into the trunk.

Enough abstraction, let's look at an example. Let's say that your changes are on a branch called snowball. You will also need an up-to-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. We will need to determine the changeset for your branch--we don't want any of the changes before you branched. Type:

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

and you will see all the relevant log messages and revision numbers.

Let's say you started your branch at revA and that the HEAD of your branch is now revB. 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 branch to your working copy of the trunk.) Now you must ensure that all is well--no conflicts, the tests pass etc--and you may commit your merged branch into 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.