Guidelines and help to commit on the trunk (or a branch)

Author: J. Ghattas
Last revision: 2023/07/04, J. Ghattas

Here are some general guidelines for committing into the trunk ORCHIDEE. These recommendations can also be applied to branches and other versions under SVN control.

Before commit:

• Run the "open trusting" to test your modifications, see here Documentation/UserGuide/Internal/OpenTrusting
• the code must be conform to the ORCHIDEE coding guidelines (Documentation/UserGuide/CodingGuidelines)
• update to latest version: the modifications must be integrated in the latest version of the trunk (use "svn update", or extract a new ORCHIDEE). Be sure that your original code is backup somewhere locally to avoid deleting developments during the update.
• if svn update induce some conflicts between your local version and the trunk version carefully check them and solve them manually if necessary. Don't forget then, once the conflicts are resolved, to do "svn resolved myfile.f90"
• the modifications must be tested on at least one platform using MPI parallelism (except if only comments are changed). This means that you should launch a test simulation on more than one processor.
• check difference in results from your history files. The reason for a change in result must be known before the commit. If possible, avoid change in results except if it was on purpose.
• communicate and/or be aware of the latest news in the ORCHIDEE core team. For example a colleague announced that she/he will make a commit, better wait or ask if you could commit before.

Some cases must be discussed in advance:

• if the behaviour of the model change. For example: change in parameter name in getin function, change in default value for some parameters, etc..
• if the interface towards the atmosphere is changed
• structural modifications

During commit:

• a commit should only resolve one problem at a time, related to one ticket.
• write a useful log message in English
• Within this log message, use #X to refer to the ticket number X (the # will make a link directly to the ticket when visualizing the log message on the web). Use [Y] to refer to another commit number Y.

After commit:

• tell the project group if the results changed even for tiny changes. A new reference must then be done in the ​trusting.
• if related to a ticket, add a link to the commit in the ticket using [Y], where Y is the revision number on the commit. Close the ticket if all questions are treated.
• if the trusting fails after commit, the commit should be reverted if a correction could not be done directly.

Basic use of SVN

See also the section svn on the Documentation/UserGuide.

Create a new file

Add a new file to the svn repository either by coping an existent, renaming or adding a new file.

svn cp file1 file2
or
svn mv file1 file2
or create first the file2 and then add it
svn add file2

All these commands will only add locally the file. To finally add them to the repository you must commit:

svn -u stat
svn ci

Example if you forgot to create ORCHIDEE_OL in your branch. First, under svn, copy ORCHIDEE_OL from a close version of your branch, then extract it to your working directory (where you develop your version). There copy/modify your configuration files, add them to svn and eventually commit:

svn cp svn://forge.ipsl.jussieu.fr/orchidee/branches/ORCHIDEE_2_2/ORCHIDEE_OL svn://forge.ipsl.jussieu.fr/orchidee/branches/ORCHIDEE-SP-MIP/ORCHIDEE_OL
cd $workdir/ORCHIDEE-SP-MIP/
svn co svn://forge.ipsl.jussieu.fr/orchidee/branches/ORCHIDEE-SP-MIP/ORCHIDEE_OL ORCHIDEE_OL 
cp -r $newconfig/OOL_SEC_STO_SPMIP ORCHIDEE_OL/OOL_SEC_STO_SPMIP
svn add ORCHIDEE_OL/OOL_SEC_STO_SPMIP
svn -u stat
svn ci

Activate revision information

If you added a new file, make sure also to activate the commit information in the header, after activation this should be done automatically at each commit. Add in the beginning of the file the following keywords :

!! $HeadURL$
!! $Date$
!! $Revision$

Activate substitution by using propset and commit the file:

svn propset svn:keywords "Date Revision HeadURL" file2.f90
svn ci file2.f90

After the commit it should look something like:

!! $HeadURL: svn://forge.ipsl.jussieu.fr/orchidee/trunk/ORCHIDEE/src_sechiba/file2.f90 $
!! $Date: 2015-09-21 13:37:38 +0200 (lun. 21 sept. 2015) $
!! $Revision: 2928 $

Update a branch with changes done in the trunk

First make sure that all changes in the branch have been committed. No local changes should exist in the folder. In a terminal, go to the directory with the source code for the branch:

cd modipsl/modeles/ORCHIDEE    # in the branch

Determine the revision interval x1:X2 with changes done on the trunk that you want to integrate in the branch Check first with --dry-run which files are affected:

svn merge --dry-run -r x1:x2 svn://forge.ipsl.jussieu.fr/orchidee/trunk/ORCHIDEE

Then do the real merge:

svn merge -r x1:x2 svn://forge.ipsl.jussieu.fr/orchidee/trunk/ORCHIDEE

If files gives conflicts, you can answer p for postpone and resolve them manually after finishing the command merge. The command svn merge will not commit any changes. All changes will be done locally and you need to validate by svn diff and svn ci to commit.

Merge changes done on a branch into the trunk

The same command svn merge can be used to merge a branch into the trunk. For this case, install locally the trunk and go to that folder. The svn command will look something like folllwing:

cd modipsl/modeles/ORCHIDEE    # in the trunk
svn merge -r x1:x2 svn://forge.ipsl.jussieu.fr/orchidee/branches/ORCHIDEE-TOTO/ORCHIDEE