How to create a new branch or personal copy

Author: J. Ghattas
Last revision: 2020/02/28, S. Luyssaert
and 2023/12 XW

Objectives

This item should help you to: (1) decide whether you need a branch or a personal copy, (2) contact the right persons to deal with the tasks that require administrator rights, (3) start your own branch or personal copy, and (4) benefit from svn to save and share your developments. Please note that this page is more oriented towards already experienced svn users if your a beginner and you want to have you personal branch please contact your supervisor who will help you with the details.

Decide whether you need a branch or a personal copy

Both a branch and a personal copy are a line of development that exists independently of another line, yet still shares a common history if you look far enough back in time. They always begin life as a copy of the trunk or another branch, and moves on from there, generating its own history.

In the ORCHIDEE context branches are established for large research projects (i.e., a team of 5 persons working towards a common goal) or specific functionalities (i.e., a one or two persons developing new functionality). This allows you to save your not-yet-completed work frequently without interfering with others' changes and while still selectively sharing information with your collaborators.

In the ORCHIDEE context personal copies are established for a single person who will work on the trunk or a branch of ORCHIDEE. Personal copies are the typical choice for an MSc or PhD project. This allows you to save your not-yet-completed work frequently, and benefit from updates made on your parent-copy.

The svn functionality of a branch and personal copy are identical, the choice is more driven by consideration related to project management than to technical consideration. Discuss with your supervisor or the ORCHIDEE-team what seems to be the most appropriate choice for the project you have in mind.

Contact the right persons to deal with the tasks that require administrator rights

First, ask for a login on svn, a personal folder on the svn repository, and a login to forge which is the website that comes with the svn server. The login on svn is essential, a login to forge is optional but could come in handy (see below). As this task requires administrator rights for the svn server, only few persons can help you with this task. If you want a quick answers send your request to the ​orchidee-help mailing list. The three administrators (Josefine, Fabienne and Nicolas Vuichard) will all receive this email. This is also a good time to decide whether you want to receive an alert every time someone of the ORCHIDEE-team has committed changes to svn. Note that you will receive emails of changes made to the trunk, all branches and personal copies. Expect tens of emails per week. By default you will NOT receive alerts, tell the administrators if you want to subscribe for svn-alerts.

The svn administrators will create a folder for your branch or personal copy in the svn server using following syntax (example for a personal copy):

svn mkdir svn://forge.ipsl.jussieu.fr/orchidee/perso/firstname.lastname

Subsequently, the administrator will set read and write access for this new branch in the svn/conf/authz file at forge and will subscribe you to the svn-alert emails if you indicated you wish so.

Start your own branch or personal copy

Note that when a branch or personal copy has been created, its folder will be empty. Your branch or copy will begin its life as a copy of the trunk or another branch. So your first task is to copy ORCHIDEE source code in your personal svn directory. Note that you can have several versions of ORCHIDEE in your folder.

For example, you want to copy revision number X from the ORCHIDEE trunk into a new folder in your personal space :

svn mkdir svn://forge.ipsl.jussieu.fr/orchidee/perso/firstname.lastname/NEWDEV1
svn cp -r X svn://forge.ipsl.jussieu.fr/orchidee/trunk/ORCHIDEE svn://forge.ipsl.jussieu.fr/orchidee/perso/firstname.lastname/NEWDEV1/ORCHIDEE_mytrunk

If you want to copy ORCHIDEE_OL into your personal space:

svn cp -r X svn://forge.ipsl.jussieu.fr/orchidee/trunk/ORCHIDEE svn://forge.ipsl.jussieu.fr/orchidee/perso/firstname.lastname/NEWDEV1/ORCHIDEE_mytrunk

You can have several version on your space.

For example you want to copy the tag 1.9.6 into your space for personal modifications :

svn cp svn://forge.ipsl.jussieu.fr/orchidee/tags/ORCHIDEE_1_9_6 svn://forge.ipsl.jussieu.fr/orchidee/perso/firstname.lastname/myORCHIDEE_1_9_6 

You are encouraged to commit all your ORCHIDEE source code to svn as well as all your pre-processing and post-processing scripts. However, do NOT commit netcdf files, executables or other big files to svn.

Save and share your developments

Check out your personal folder

The svn-server archives the source code but it cannot be used to run ORCHIDEE. Running ORCHIDEE requires you to check out (hence the co in the command svn co) the source code from svn and to download it to one of the servers where you can run the model (e.g., Obelix, Irene, Climserv). You can copy the code that has been archived in your personal folder by the following command line (replace firstname.lastname by yours):

svn co svn://forge.ipsl.jussieu.fr/orchidee/perso/firstname.lastname mypersofolder

If you get the error message "svn: Authorization failed", then add --username firstname.lastname to the svn command.

svn --username firstname.lastname co svn://forge.ipsl.jussieu.fr/orchidee/perso/firstname.lastname mypersofolder

When you copied your preferred version of ORCHIDEE into your branch or personal copy at the very begin (see above) and you followed the instructions above, you have only copied the ORCHIDEE folder which contains the source code. To install a working copy of ORCHIDEE you also need many other folders (which you don't want to store in your svn folder because you will not develop those). One way to install a working copy is to first ​download the trunk, then delete the ORCHIDEE folder of the trunk (rm -rf ORCHIDEE) and then download your ORCHIDEE copy in the folder where the trunk ORCHIDEE folder (you just deleted) was (using svn co).

If you want to download ORCHIDEE (or ORCHIDEE_OL) from your branch to your home working folder, then you need follow the instructions in the part of Branch in ​https://forge.ipsl.jussieu.fr/orchidee/wiki/Documentation/UserGuide/InstallingORCHIDEEBasic, by modifying the ORCHIDEE/ORCHIDEE_OL with your branch version.

Visualize your folder using the web interface

This is where the forge login comes in handy. If you have a login for forge where the wiki and svn of ORCHIDEE are stored, you can visualize your account on any browser

https://forge.ipsl.jussieu.fr/orchidee/browser/perso].

Ask for an account on forge using the email list ​orchidee-help. This login can also be used to modify the wiki, create and comment on tickets and visualize your personal folder as well as the trunk and all branches you have access to.

Saving and sharing your developments

When you copied your preferred version of ORCHIDEE into your branch or personal copy at the very begin (see above) and you followed the instructions above, you have only copied the ORCHIDEE folder which contains the source code. Maybe you also want to store other source code in your personal folder such as pre-processing and post-processing scripts (but do NOT commit netcdf files, executables or other big files to svn). You can tell svn there are new files you would like to place on the svn-server

svn add MY_SCRIPT_FOLDER/newfile.py -m "New: some explanation here"

Once your developments are working you can save your changes on svn so that the history of the code is traceable. At the time you save your file you also share them with the other users of your version. This could be half the world in case of the trunk, a hand full of users in case of a branch or just you in case of a personal copy.

svn commit -m "New: add some message here"

svn will only commit the files under svn control and in the directory where you type the above command. For the example we have been using above this implies that you have to go to the ORCHIDEE folder and use the above command if you want to commit your ORCHIDEE source code. If you want to commit your pre-processing or post-processing scripts you first need to go to MY_SCRIPT_FOLDER and execute the command from there.