Repository layout and TM5 version control strategy

From tm5
Jump to: navigation, search

This page introduces the repository layout and explain a number of best practices with respect to the version control strategy. The repository is first described, and the strategy is summarized at the end.


Base & projects

The TM5 repository is better seen as a collection of svn-projects. Users build TM5 by combining code sources from several of these projects (see [[Building and compiling TM5|Building TM5]]). One particular project is the base/, which contains the core routines (meteo, transport, program control flow). All other projects are under the proj/ directory. They can define the tracers, their sources and sinks, and more. Here is an overview of the top structure:

 |-- base
 |-- proj
 |    |-- alanis
 |    |-- budget
 |    |-- c13
 |    |-- chem
 |    `-- ...
 |-- TM
 `-- tools

The full list of projects under proj/ can be seen on the web interface or on the Administrators page. It can also be display with:

 svn list

Note also the two extra directories:

The base/ and each of the TM projects have the same tree structure, with at least a trunk and, as needed, release/ and/or branches/ directories:

 |-- branches
 |	|-- <branch0> 
 |	|-- <branch1> 
 |	`-- ...
 |-- release
 |	|-- 3.0 
 |	|-- 4.0 
 |	`-- ...
 `-- trunk
       |-- bin   # scripts 	
       |-- py    # more scripts 	
       |-- rc    # configuration files 	
       `-- src   # code source 	

The bin, py, rc, src directories of the trunk/ are repeated under each of the branches and releases.


The trunk gathers developments towards the next release.

Although development can be directly done in the trunk, it should be advanced by integrating branches (merging) after approval by either the project administrator or the Steering Committee, depending on the user base concerned.

Direct commits to the trunk should be exceptional, and reserved to minor changes that have no direct impact on the other projects. This should be enforced for the base, since changes in the base/trunk can affect all other projects. We really want to keep the trunk technically stable (compiles and runs)!


Main developments happen in branches, which typically start as a copy of a trunk. See Creating a new branch. Users are encouraged to branch a project. You have almost no restrictions in your branches: just do not put data set in the repository!

Branches greatly facilitate sharing development, and there is no reason to not use a branch for your development. Keeping your branch in sync with its corresponding trunk is explained in Staying in sync.

Once a development branch is mature and tested, it can be merged back into the trunk of the project. This can be done by the development team (DT) if needed. Approval for merging is given by the Steering Comittee and/or the TM-project administrator, depending on the project.

Once reintegrated into the trunk, a development branch cannot be used anymore (i.e. further svn merging will not work). So, it should be deleted. To keep working with your branch, just recreate it with a brand new copy of the trunk.


Once agreed by the steering committee (ST), a release is made. It basically is a svn copy of the trunk, but a frozen one: Releases are special branches that are not modified or edited. Users that do not plan to modify the code can checkout a release branch.

Minor release: Maintenance branch associated with a release must be created to port bug fixes. Once agreed by the steering committee, a minor release can be made by making an svn copy of the maintenance branch.


Remember that for any SVN work, users can seek help from the DT. Following the previous paragraphs, the strategy can be summarized as follows:

New projects (eg, with new tracers) can also be created. See how to create a new project.

Following this strategy, the steps for a minimal installation of TM5 code for development would be:

  1. find out/decide which projects you need and which one you plan to modify
  2. for each of the projects you want to modify:
    1. create your branch in the repository as a copy of the trunk
    2. checkout that branch
  3. for each of the projects you will not modify:
    1. checkout the trunk

However, we recommend that users checkout entire projects. It significantly simplifies maintenance, merging, documentation and support. See how to check out the code for details.

Personal tools