How to create a new branch or personal copy

Author: J. Ghattas Last revision: 2020/02/28, S. Luyssaert

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, and (3) benefit from svn to save and share your developments.

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 (​http://svnbook.red-bean.com/en/1.7/svn.branchmerge.whatis.html).

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 and a personal folder on the svn repository. 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. Note that When a branch or personal copy has been created, its folder will be empty.

benefit from svn to save and share your developments

Here is some short help on how to create and commit in a personal directory or a branche.

Create your personal folder

Commit in your folder

In your personal svn directory you can now commit source code and scripts. You should not commit netcdf files, executables or other big files. You can have several versions in your folder.

For exemple you want to copy revision number X from the ORCHIDEE trunk into your remote personal folder :

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

For exemple you want to copy the tag 1.9.6 into your remote personal folder :

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 

Extract your personal folder

Your personal folder can be extracted by the following command line (replace firstname.lastname by yours):

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

If you got error message "svn: Authorization failed", then add --username firstname.lastname in the commande svn.

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

Vizualise your folder using web interface

If you have a login to the machine forge where the wiki and svn of ORCHIDEE are stored, you can visualize your account at forge: ​https://forge.ipsl.jussieu.fr/orchidee/browser/perso. Ask for an account on forge using the email list orchidee-help. This login can be used to modify the wiki, to create and comment tickets and to vizualize your personal folder as well as all branches you have access to.

Starting from zero

This small guide explains how to properly commit your Orchidee source code into the Subversion for the first time.

If you follow this guide, then the subversion will properly keep track of the modifications done in the code (what you see in svn log).

1. Create a new perso folder in the Subversion to place your files: Check here

2. Copy your starting Orchidee version (e.g: orchidee-som revision 5054) to your perso folder (in server).

svn copy -r 5054 svn://forge.ipsl.jussieu.fr/orchidee/branches/ORCHIDEE-SOM/ORCHIDEE svn://forge.ipsl.jussieu.fr/orchidee/perso/haicheng.zhang/ORCHIDEE-MUSLE -m "Branch: some decription here"

This step is specially important because it will allow the svn to keep track of any modification done in the code.

3. Download the code from the server to your local machine:

svn co svn://forge.ipsl.jussieu.fr/orchidee/perso/haicheng.zhang/ORCHIDEE-MUSLE ORCHSVN-MUSLE

4. Bring all the modifications from your code (in local) to the downloaded folder ORCHSVN-MUSLE (in local)

cd ORCHSVN-MUSLE

cp /YOUR/ORCH/FOLDER/src_stomate/*90 src_stomate/

cp /YOUR/ORCH/FOLDER/src_sechiba/*90 src_sechiba/

cp /YOUR/ORCH/FOLDER/src_global/*90 src_global/

cp /YOUR/ORCH/FOLDER/src_xml/*xml src_xml/

...

For all the src_ folders. Make sure to procede this way to not mess it up with some hidden files.

5. Tell subversion there are new files (if applies)

svn add src_somewhere/newfile.f90 -m "New: some explanation here"

6. Send the modifications done to the code to the server

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