wiki:HowToUseVersionControlSystem

Version Control System guide

This article describes how to use the OpenTURNS' version control system also known as subversion repository or even repository. These instructions may be useful for OpenTURNS' developers which have an account on our subversion server.

You should use a recent version of subversion (1.6.4 or later) in order to avoid merge conflicts

File hierarchy

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

  • trunk
  • tags
  • branches

Each user have a dedicated branch under the branches directory. The name of the branch is often the developer's last name. For instance, John Doh known as user doh has a branch /branches/doh. The developer is responsible for the content of his branch.

Note 1: The creation of the branch is made by a repository administrator on an Open TURNS Executive Committee demand.

Note 2: We may decide to close a branch, with or without valuable work, if the content of the branch or the developer's usage of the repository impairs the repository sanity.

We will explain how each directory is used by commenting an example. Let's assume John Doh wants to add some new functionality to Open TURNS.

Step 1: the branch creation

Server side :

  1. the subversion's administrator creates a new account named doh for user John Doh;
  2. then it creates new directory in /branches/doh : the user's 'private' branch. This branch is a copy of the last revision of the trunk.

Step 2: the working copy

Subversion is a quite loose coupled version control system, so the developer has no need to be connected through the network to the repository all the time. The connection is needed during specific interactions with the server. See Subversion manual for more details.

When disconnected from the network, the developer works on a local copy of its branch. This copy is named the working copy or WC in brief. Many daily subversion commands work on the working copy.

Client side :

  1. John Doh can now "checkout" its private branch. This will create the working copy on the developer's file system.
    svn checkout https://svn.openturns.org/openturns/branches/doh doh-branch
    
    The working copy now lives in the doh-branch directory. We encourage you to have multiple simultaneous working copies of your branch to split the developments concerning different functionalities.
  1. John Doh can now develop what he has to do. But he must keep in mind:
    • to add or delete the file that should go to the repository
    • not to move files around in his working copy (or worse in the repository). Before moving a file, be sure the know what you're doing!
    • to log every change as soon as it is made in any way in order to prepare the future commit log.
  1. Each functionality, bug fix, etc. must be committed separately with a meaningful comment.

Note 3: Do not make large commits, because it is quite impossible to separate changes we want to keep from those we want to roll back. Do make very small commits.

For instance if John Doh write an enhanced cache system :

svn commit -m "Introduced 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 shows what has 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 integrator will refuse to merge your developments.

First you have to resynchronize your branch with the trunk.

  1. Checkout the branch to merge (ie: for John Doh)
    svn co https://svn.openturns.org/openturns/branches/doh doh-branch
    
  2. Find the latest synchronization (with trunk) revision of this branch. You have to search for the latest MERGE or BRANCH keyword in the log of your branch
    svn log | egrep -B6 -e '^(BRANCH|MERGE)'
    
    Suppose the output is:
    ------------------------------------------------------------------------
    r370 | doh | 2008-09-22 11:34:11 +0200 (Mon, 22 Sep 2008) | 18 lines
    
    MERGE: doh> svn merge -r 321:365 https://.../trunk
    ...
    
    Here we suppose that the latest synchronization was done for revision 370 (r370) and includes the modifications of the trunk from revision 321 to revision 365.
  3. Apply differences between the latest synchronized revision (r365) and the latest revision of trunk (r620) to branch
    cd doh-branch
    svn merge -r 365:620 https://svn.openturns.org/openturns/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
    make
    make distcheck
    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 is no error, commit this revision with a special log message
    svn commit -m 'MERGE: svn merge -r365:620 https://.../trunk
    
    Synchronization with trunk.
    Make distcheck ok.'
    
    When committing, don't forget to add the correct keyword (MERGE, BRANCH, TAG) for the next merge. Otherwise it will be very painful to find the latest synchronization point.

Don't forget also to mention in the commit log that make distcheck succeeded. If not, the integrator will refuse to merge your work.

Tagging and releasing process

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

TO BE DOCUMENTED

Here we suppose that all merging process is done. The trunk is clean and is ready to be released as an official version.

Tagging

  1. First, before tagging, set the correct version number :
    cd trunk && ./setVersionNumber.sh 0.15.0
    # Verify that compilation and archive creation process work fine with this updated version of '''trunk'''
    cd .. && svn export trunk/ test-trunk-linux && cd test-trunk-linux && ./bootstrap && ./configure && make && make distcheck && cd ..
    svn commit -m "Changed version number to 0.15.0."
    
  1. Then, you can now tag your new version with following commands
    svn copy trunk https://svn.openturns.org/openturns/tags/openturns-0.15.0 -m 'TAG: This is official release 0.15.0.'
    # or svn copy trunk https://svn.openturns.org/openturns/tags/openturns-0.15.0rc1 -m 'TAG: This is pre-release 0.15.0rc1.'
    

Releasing

  1. Export newly created tag in a temporary folder
    cd /tmp
    svn export https://svn.openturns.org/openturns/tags/openturns-0.11.3
    
  1. Bootstrap, configure and make your tagged version
    cd openturns-0.11.3
    ./bootstrap
    ./configure --with-swig
    make
    
  1. Build tarball
    make dist
    ls *.tar.*
    
Last modified 6 years ago Last modified on 07/07/11 14:59:58