SVN - Best Practice/FAQ

We encourage developers to use branches when developing the model. Do you find version control, branching and merging a bit difficult, try the NorESM svn branch/merge tutorial to understand branching and merging. In 30 minutes you can become an svn wizard

Follow this link to find the tutorial: SVN Branch/Merge tutorial

Branches

What is a branch?

A branch is your own version of the repository. Sometimes it is nice to work on a feature “in private” without having to relate to other developers' codes. And sometimes you want to work on something which takes some time before it is finished.

In these cases you can create a branch. You can work on it on your own or in a team of colleques. When you are happy with the the content of the branch, you can merge it back to the trunk.

The trunk is considered a safe repository. The code in the trunk should always have passed a set of tests to make sure it is stable.(https://wiki.met.no/noresm/testlist)

Branches let you take advantage of the svn features, but without having to worry every day that your code passes the tests.

Create a branch with (http://svnbook.red-bean.com/en/1.7/svn.branchmerge.using.html)

$ svn copy http://svn.example.com/repos/calc/trunk \
http://svn.example.com/repos/calc/branches/my-calc-branch \
-m "Creating a private branch of /calc/trunk."

Then check out the branch using

svn checkout $BRANCHURL nameOfBranchOnMyPC

When should I work on a branch?

In most cases the answer is “always”. However look at it this way:

If you work directly on the trunk you have to check that your code passes the tests every time you change the code. This is cumbersome and takes a lot of time. However if you are on a branch, you can work peacefully together with your small team taking full advantage of the version control system. In the end, when you and your teammates are happy with the changes, you perform the tests and merge back to trunk.

You should obviously test your code also before you commit to a branch, but for a branch the test does not include running and analyzing long simulations.

How should I name the branch?

The NorESM branches have the following naming convension : {PurposeOfLife}_{ParentTagName}. This means that a branch name should state why it is created and where it is created from.

PurposeOfLife is a text string (a-z, A-Z and 0-9) must start with “Release”, “Feature” or “Private”. Is your branch a “feature”, “release” or “private branch”? Find out on http://svnbook.red-bean.com/en/1.7/svn.branchmerge.commonpatterns.html

ParentTagName is the name of an existing noresm tag.

Examples of valid branch names are:

FeatureIceActivation_trunk-2.0 (Development of ice activation feature, branched off from trunk 2.0)

PrivateIngo_trunk-2.1 (Ingo's private development branch, branched off from trunk 2.1)

Note that in this scheme a tag MUST be created before creating a branch (see section on tags below)

How and when should I merge from trunk to my branch?

You can decide this for yourself. The main hypothesis is that the trunk is always stable and working, so you will not harm your branch by merging from trunk. If you are working on something which you will finally merge back to the trunk, you can merge often. Then the final merge will be easier.

Just use svn merge ^/noresm/trunk (The “^” means “the URL of the repository's root directory“ in newer versions of svn. In older versions you need to give full URL)

How can I merge my branch back into the trunk?

You can merge to trunk after your changed code has passed a list of tests. The tests are available here: https://wiki.met.no/noresm/testlist

If your code does not pass the tests, you can not merge your code back to the trunk

Note that in svn, you can only merge ONE time from your branch to the trunk, or you risk making a mess of the system! (See http://svnbook.red-bean.com/en/1.7/svn.branchmerge.basicmerging.html ==> “Reintegrating a branch”, note the statement Once a --reintegrate merge is done from branch to trunk, the branch is no longer usable for further work”)

The merge command (from trunk) will be something like (http://svnbook.red-bean.com/en/1.7/svn.branchmerge.basicmerging.html)

svn merge --reintegrate $BRANCHURL

Tags

What is a tag?

A tag is a version of the model which should be considered “frozen”. It makes sense to make a new “tag” for a production system, for example a specific version which should be used for many runs.

In svn notation, there is no difference between a branch and a tag. It is just a question of naming convension. Recommended convension is that tags are branches saved under the “tags” subdirectory and a branch is saved under the “branches” directory.

In NorESM tags are considered frozen, and people are not allowed to do developement on tagged versions.

Create the tag with a command like (http://svnbook.red-bean.com/en/1.6/svn.branchmerge.tags.html)

svn copy http://svn.example.com/repos/calc/trunk \
http://svn.example.com/repos/calc/tags/release-1.0 \
-m "Tagging the 1.0 release of the 'calc' project."

When should I create a tag?

You should create a tag in the following cases:

When you want to create a branch! Always tag the model first and then create the branch from the tag.

A “released” version, a version which has been properly tested and which we recommend other users to run

A version which has been used for some specific paper (maybe you want to do more runs after referee comments)

How should I name the tag?

Tags have the naming convension {ParentPurposeOfLife}-{IncreasingVersionNumber}.

The tags don't have their “own” purpose of life, they use the ones they were created from!. The increasing version number is a one digit number for all branches. Trunk has a two-digit increasing version number where the first number is the NorESM main version (NorESM1, NorESM2 etc).

Examples are:

trunk-2.1

trunk-2.2

PrivateIngo-1

FeatureIceActivation-1

Note how this is consistent with the branch naming scheme. You actually need to create a tag in order to give your branch a proper name!

Tricky Use cases

Case 1

A user has performed a control simulation using a tagged NorESM version. He wants to use this control simulation as baseline for several new implementations. How should he create/update working branches without having to worry about changes in trunk that can affect the result?

This is straight forward. The user creates several branches based on the original tag. Following the naming convension scheme, they all have a different “PurposeOfLife” but they have the same ParentTagName. The combination is a unique branch name for all the new implementations.

Case 2

A tagged NorESM version has been used for the production of a certain simulation. Part of the simulations has to be rerun with extended diagnostic capability (e.g., with U10 output). How can I commit the extended diagnostic capability to svn?

One can imagine that something like this happened:

The originally tagged version was made from a branched called “ReleaseExperimentX_trunk-2.45”

The experiment was run with “ReleaseExperimentX_3”

When the update is needed there are two possibilities:

Option 1

This is the normal (and simplest) case:

Update the “ReleaseExperimentXVersion_trunk-2.45” branch with the changes needed. After the development is done on “ReleaseExperimentXVersion_trunk-2.45” brand, tag this as “ReleaseExperimentX-4” and do the experiments.

Option 2

In the mean time, someone has done a lot of bugfixing in “ReleaseExperimentX_trunk-2.45”, so the latest version of “ReleaseExperimentXVersion_trunk-2.45” is significantly different from “ReleaseExperimentX_3” and you are afraid including the bugfixes will change the original results. You can not include all the bugfixes before doing the extra simulations so using the latest version of “ReleaseExperimentX_trunk-2.45” is not an option.

In this case, create a new branch: “ReleaseExperimentX_ReleaseExperimentX-3” (alternatively “ReleaseExperimentXForPaperReview_ReleaseExperimentX-3”), update it and tag it “ReleaseExperimentX-4”.

You have to consider the following: Do you want to create a new “PurposeOfLife” in this case? It depends on the amounts of the bugfixes. Probably you want the bugfixes anyway at some later stage (there was a reason someone put them there!!) Then you don't need a new “PurposeOfLife”.