Version Control System guide

This article describe how to use the OpenTURNS' version control system AKA subversion repository. These instructions may be useful for OpenTURNS' developers which have an account on subversion.

File hierarchy

As usual with subversion repository, root directory contains three directories described bellow :

  • trunk
  • tags
  • branches

Each user have a personal branch named simply by username. Every branch must be follow some rules to be more easy to merge with others developments. These rules are really simple:

  • at the first time, developer must create one devel directory by copying trunk using conventional commit message (see below);
  • if developer want made some support on one or more major version, he must copy a tag also using special commit message;
  • NEVER developer had to applying patch manually across subversion directory: always use svn merge to do that;
  • NEVER merge branch with another : all merge must be done from or to trunk.

In example, with one developer "John Doh" which want to develop new features (devel) and provide some support for 0.11.x (support-0.11), the file hierarchy looks like this:

  • trunk
  • tags
    • openturns-0.11.0
    • openturns-0.11.1
    • openturns-0.11.2
    • openturns-0.11.3
  • branches
    • doh
      • devel
      • support-0.11

It is more simple to explain how each directory is used by comment an example of development made by upcoming developer in OpenTURNS' repository :

Server side :

  1. Subversion's administrator create a new account named "doh" for user John Doh;
  2. Subversion's administrator create new directory in /branches/doh/ : the 'private' user branch;

John Doh now can begin to work with repository, at the first time developer must "branch" the trunk, which is the reference of all the repository. In the trunk, we try to keep the latest working development version.

Client side :

  1. John Doh can now "checkout" its private branch 
    svn checkout https://svn.openturns.org/branches/doh doh-branch
  2. To be able to develop with the latest version, John copies the trunk's content to a subdirectory. The name of this subdirectory is an major information for the integrator of your developments. If your directory is named "devel", then the integrator will suppose that your are developing for the next release, so he will merge your developments in the trunk's head. If you name your directory something like "support_x.y" where x and y are the version number and the release number, it means that you are performing maintenance for the version x.y. Everything else is some private development not intended to be merged. So be careful when naming your directory.

You may have multiple contiguous directory in your branch to split your developments according to their targets.

Here we suppose that the developments will be merged in the trunk, for example these are a new functionality. 

cd doh-branch
svn copy https://svn.openturns.org/trunk devel
  1. The previous step have locally added all trunk's content into your devel subdirectory, John must NOW make his first commit : 
    svn commit -m "BRANCH: svn copy https://.../trunk devel"
    To ease the managment of version control system, we need (and impose) to use comment for each commit. When the commit concerns a branch transform such as a copy, a merge, a delete, a tag or anything similar, we need to see the appropriate keyword in the log message. Those are:
    • BRANCH for branch creation or deletion
    • MERGE for merge between branches (in either direction)
    • TAG for tags
  2. John Doh can now develop in devel subdirectory. 
    cd devel
...
  3. Each step (ie functionality, bug fix, etc.) must be commited separately with a comment. ie if John Doh write an enhanced cache system : 
    svn commit -m "Introduce an enhanced cache system."
    The -m option is useful for single line comments, ie for very small comments. If your commit needs to be explained in a few lines, it is better to log the entire comment in a plain text file (ie, svn.log is a quite common name) and to use the -F option followed with the file name. 
    edit svn.log
svn commit -F svn.log

Merging process

This chapter is dedicated to the developers works merge process and shows what is to be done before the integrator can merge your developments.

The whole process must succeed in order to be able to merge. If any failure occurs, it MUST be corrected. Otherwise the subversion repository will be corrupted.

  1. Checkout the branch to merge (ie: for John Doh) 
    svn co https://svn.openturns.org/branches/doh/devel doh-devel
  2. Find the latest synchronization (with trunk) revision of this branch (in our example r365). You can search for the latest MERGE or BRANCH keyword in the log of your branch 
    svn log | egrep -B6 -e 'BRANCH|MERGE'
    Here we suppose that the latest synchronization was done for revision 365 (r365).
  3. Apply differences between the latest synchronization (r365) and the latest revision of trunk (r620) to branch 
    cd doh-devel
svn merge -r365:620 https://svn.openturns.org/trunk
  4. Verify patched files and conflicts 
    svn status | egrep -e ’^C’
svn status | egrep -v -e ’^[DRAM]’
    Those commands should not return any error or missing files.
  5. Verify that compilation and archive creation process work fine with this updated version of branch 
    ./bootstrap
mkdir build && cd build
../configure --prefix=$PWD/install
make
make distcheck DISTCHECK_CONFIGURE_FLAGS='--without-swig'
cd -
    In this process, it is mandatory to build and test the development in a separated directory. So DO make a subdirectory build and DO change do it. It does not eat time but it ensures that the building process is correct (you can't check for this when building in the same directory).
  6. If there no error, commit this revision with a special log message 
    svn commit -m 'MERGE: svn merge -r365:620 https://.../trunk'
    When commiting, don't forget to add the correct keyword (MERGE, BRANCH, TAG) for the next merge. Otherwise it is very painful to find the latest synchronization point.

Tagging and releasing process

This chapter explains how integrator must tag and release a new version with this version control system.

Add this step, we suppose that all merging process is done; The trunk is clean and is ready to be released as an official version.

Tagging

1. The first step, before tagging, is to update all ChangeLog file very a pretty tool : 'svn2cl' 

for i in `find ./ -name "ChangeLog"`; do
 DIR=`dirname $i`;
 cd $DIR; svn2cl -i;
 cd -;
done

2. Edit 'configure.ac' files to set the new release version 

for i in `find ./ -name 'configure.ac'`; do
  sed -e "s:\[0.11.2\]:[0.11.3]:" $i > $i.sed && mv $i.sed $i;
done

3. You can now commit these modifications 

svn ci -m 'Next release (0.11.3) preparation.'

4. Finally, you can now tag your new version with following commands 

cd ..
svn copy trunk tags/openturns-0.11.3
svn ci -m 'TAG: This is official release 0.11.3.'

Releasing

1. Export newly created tag in a temporary folder 

cd /tmp
svn export https://svn.openturns.org/tags/openturns-0.11.3

2. Bootstrap, configure and make your tagged version 

cd openturns-0.11.3
./bootstrap
./configure
make

3. Build tarball 

make distcheck DISTCHECK_CONFIGURE_FLAGS='--without-swig'
cd ..
ls *.tar.*