Repository layout and TM5 version control strategy
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:
TM5 |-- base | |-- proj | |-- alanis | |-- budget | |-- c13 | |-- chem | `-- ... |-- TM | `-- tools
svn list https://svn.knmi.nl/svn/TM5/proj
Note also the two extra directories:
TM: contains obsolete, older code
tools: suite of standalone (ie not strictly needed for TM5) tools
base/ and each of the TM projects have the same tree
structure, with at least a
trunk and, as needed,
base |-- branches | |-- <branch0> | |-- <branch1> | `-- ... |-- release | |-- 3.0 | |-- 4.0 | `-- ... `-- trunk |-- bin # scripts |-- py # more scripts |-- rc # configuration files `-- src # code source
bin, py, rc, src directories of the
trunk/ are repeated under each of the branches and releases.
trunk gathers developments towards the next
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:
- Developing: all developments are done into branches, except for very small edits, for which a branch would be alive for a very short time, and which do not affect other users who rely on the corresponding trunk. This is mandatory for the base, and highly recommended for the projects under the
- Merging: reintegrating a branch into a trunk is the responsibilty of the administrator of the TM project, with those specifics:
proj: while merging a branch into the trunk of a project, compatibility with the
basehas to be maintained.
proj/levels: merging branches into the trunk has to be approved by the steering comittee.
- Releasing: releases are decided by the steering committee, and made by the DT and ST.
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:
- find out/decide which projects you need and which one you plan to modify
- for each of the projects you want to modify:
- create your branch in the repository as a copy of the trunk
- checkout that branch
- for each of the projects you will not modify:
- 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.