Differences
This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
noresm:svnbestpractice [2013-12-13 08:38:07] alfg [Tricky Use cases] |
noresm:svnbestpractice [2022-05-31 09:29:32] (current) |
||
---|---|---|---|
Line 4: | Line 4: | ||
Follow this link to find the tutorial: [[NORESM: | Follow this link to find the tutorial: [[NORESM: | ||
- | ===== Branches ===== | + | |
+ | **Note: As of November 13th 2015, NorESM uses git as version control system. The rules and guidelines for merging/ | ||
+ | ===== Branches ===== | ||
==== What is a branch? ==== | ==== What is a branch? ==== | ||
Line 18: | Line 20: | ||
Create a branch with (http:// | Create a branch with (http:// | ||
< | < | ||
- | $ svn copy http:// | + | |
| | ||
-m " | -m " | ||
+ | </ | ||
+ | or specifically for the NorESM repository with | ||
+ | < | ||
+ | svn copy https:// | ||
+ | | ||
+ | -m " | ||
</ | </ | ||
Line 26: | Line 34: | ||
< | < | ||
svn checkout $BRANCHURL nameOfBranchOnMyPC | svn checkout $BRANCHURL nameOfBranchOnMyPC | ||
+ | </ | ||
+ | |||
+ | |||
+ | In git: First create your new branch locally and then make the remote aware of the new branch like so: | ||
+ | < | ||
+ | git checkout -b my_branch_name | ||
+ | git push -u origin my_branch_name | ||
+ | </ | ||
+ | |||
+ | ..and make sure your .gitconfig-file is configured for doing a merge (for example): | ||
+ | < | ||
+ | [merge] | ||
+ | tool = vimdiff | ||
+ | [diff] | ||
+ | tool = vimdiff | ||
</ | </ | ||
Line 38: | Line 61: | ||
==== How should I name the branch? ==== | ==== 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. | + | The NorESM branches have the following |
- | PurposeOfLife is a text string (a-z, A-Z and 0-9) must start with " | + | PurposeOfLife is a text string (allowed characters are a-z, A-Z, 0-9 and " |
+ | * a // | ||
+ | * a //release// branch is created if a version with frozen functionality is desired. The development on the release branch itself is limited to bug fixes, addition of forcing scenarios and other minor changes. Releases branches are not reintegrated. | ||
+ | * a //project // branch is similar to a release branch. For some projects a specific version with small changes might be required to do specific model runs. It is important that all members of the project use the same code. If the project involves major development tasks, the project team should concider creating a //feature// branch instead. A //project// branch is likely not reintegrated. | ||
+ | * a //private// branch can be created if a project requires a strongly tailored version of the model, that typically is maintained by only one person. Commits to a private branch should be agreed on with the branch creator. Private branches are not necessarily reintegrated. | ||
ParentTagName is the name of an existing noresm tag. | ParentTagName is the name of an existing noresm tag. | ||
Examples of valid branch names are: | Examples of valid branch names are: | ||
- | * FeatureIceActivation_trunk-2.0 (Development | + | * '' |
- | * PrivateIngo_trunk-2.1 (Ingo' | + | * '' |
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
- | Note that in this scheme a tag MUST be created before creating a branch (see section on tags below) | + | Note that in this scheme a new branch is never branched off directly from trunk or another branch. **A tag MUST be created before creating a branch** (see section on tags below). |
+ | |||
+ | Note that purposeOfLife of release-branches contains version numbers. " | ||
+ | |||
+ | ==== A note on branch / tag naming ==== | ||
+ | |||
+ | === Naming of feature branches and associated tags === | ||
+ | |||
+ | Consider the following example: A small group decides to have a branch of their own. The group defines their branch' | ||
+ | |||
+ | They can now branch off from trunk and create the branch '' | ||
+ | |||
+ | After the feature is completed, the branch is merged back to trunk, and following svn recommendations, | ||
+ | |||
+ | The team still want their branch on which they cooperate well. They should now re-generate their branch from trunk, for example '' | ||
+ | |||
+ | While developing on '' | ||
+ | |||
+ | The repository now has four tags: '' | ||
+ | |||
+ | === Naming of release branches and associated tags === | ||
+ | |||
+ | The PurposeOfLife string of a release branch should begin with " | ||
+ | |||
+ | The numbers < | ||
+ | |||
+ | For more information on < | ||
==== How and when should I merge from trunk to my branch? ==== | ==== How and when should I merge from trunk to my branch? ==== | ||
Line 62: | Line 118: | ||
If your code does not pass the tests, you can **not** merge your code back to the trunk | 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:// | + | 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:// |
The merge command (from trunk) will be something like (http:// | The merge command (from trunk) will be something like (http:// | ||
< | < | ||
svn merge --reintegrate $BRANCHURL | svn merge --reintegrate $BRANCHURL | ||
+ | </ | ||
+ | |||
+ | Using git, just use | ||
+ | < | ||
+ | git merge branchNameIWantToMergeWith | ||
</ | </ | ||
===== Tags ===== | ===== Tags ===== | ||
Line 80: | Line 141: | ||
Create the tag with a command like (http:// | Create the tag with a command like (http:// | ||
< | < | ||
- | svn copy http:// | + | |
| | ||
-m " | -m " | ||
+ | </ | ||
+ | or specifically for the NorESM repository with | ||
+ | < | ||
+ | svn copy https:// | ||
+ | | ||
+ | -m " | ||
</ | </ | ||
Line 88: | Line 155: | ||
You should create a tag in the following cases: | 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**. | + | * When you want to create a branch! **Always tag the model first and then create the branch from the tag**. |
* A " | * A " | ||
* A version which has been used for some specific paper (maybe you want to do more runs after referee comments) | * A version which has been used for some specific paper (maybe you want to do more runs after referee comments) | ||
+ | |||
+ | ==== What tags exist? ==== | ||
+ | |||
+ | All tags are in https:// | ||
==== How should I name the tag? ==== | ==== How should I name the tag? ==== | ||
- | Tags have the naming | + | Tags created from trunk have the naming |
+ | trunk{MainModelVersion}.{MinorModelVersion}-{IncreasingVersionNumber} | ||
- | The tags don' | + | Tags created from branches |
+ | {BranchPurposeOfLife}-{IncreasingVersionNumber} | ||
+ | |||
+ | Every time a release branch is created from trunk, then MinorModelVersion is increased and IncreasingVersionNumber reset to 1. If no new release branch | ||
+ | |||
+ | **Important: | ||
+ | |||
+ | MainModelVersion and MinorModelVersion are global counters while IncreasingVersionNumber is local to the trunk or a specific branch. | ||
Examples are: | 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!** | 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!** | ||
+ | ==== Tagging noresm0 and noresm1 branches? ==== | ||
- | ===== Tricky | + | NorESM0 and NorESM1 had a quite random naming convension for branches where branch names involved " |
+ | |||
+ | Therefore, even though it is confusing it is proposed here to use " | ||
+ | |||
+ | **purposeOfLife of NorESM1 branches is therefore whatever follows after " | ||
+ | |||
+ | ===== Tricky | ||
==== Case 1 ==== | ==== 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 | + | //A user has performed a control simulation using a tagged NorESM version. He/she wants to use this control simulation as baseline for several new implementations. How should |
+ | |||
+ | This is straight forward. The user creates several branches based on the original tag. Following the naming convension scheme, they all have a different " | ||
+ | |||
+ | Importantly, | ||
- | This is straight forward. The user creates several branches based on the original tag. Following the naming convension scheme, they all have a different " | ||
- | |||
==== Case 2 ==== | ==== Case 2 ==== | ||
+ | |||
+ | //A user group wants to develop one model component without constantly having to worry about changes in other model components.// | ||
+ | |||
+ | A solution is to bundle new implementations for a specific component by creating a super branch (e.g., '' | ||
+ | |||
+ | The super branch can then be used to create ordinary feature branches for the individual implementations (e.g., '' | ||
+ | |||
+ | Reintegration into trunk is done in two steps: First, feature branches from the individual implementations are reintegrated into the super branch. Last, the super branch is reintegrated into trunk. | ||
+ | |||
+ | ==== Case 3 ==== | ||
// 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?// | // 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: | One can imagine that something like this happened: | ||
- | * The originally tagged version was made from a branched called "ReleaseExperimentX_trunk-2.45" | + | * The originally tagged version was made from a branched called "release2.0.0_trunk2.0-45" |
- | * The experiment was run with "ReleaseExperimentX_3" | + | * The experiment was run with "release2.0.0-3" |
When the update is needed there are two possibilities: | When the update is needed there are two possibilities: | ||
Line 125: | Line 227: | ||
== Option 1 == | == Option 1 == | ||
- | Update | + | This is the normal (and simplest) case: |
- | This is the normal case. | + | Update the " |
== Option 2 == | == 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 the mean time, someone has done a lot of bugfixing in "release2.0.0_trunk2.0-45", so the latest version of "release2.0.0_trunk2.0-45" is significantly different from "release2.0.0-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 "release2.0.0_trunk2.0-45" is not an option. |
+ | |||
+ | In this case, create a new branch: " | ||
+ | |||
+ | ===== SVN messages ===== | ||
+ | |||
+ | ==== What should be stated in the commit message? ==== | ||
+ | |||
+ | **Always state the JIRA issue associated with the work**! This makes the code changes pop up in JIRA!: For example "svn commit -m " | ||
+ | |||
+ | The commit message should include a concise description of the committed changes. | ||
+ | |||
+ | Furthermore, | ||
+ | |||
+ | Examples 1: | ||
+ | Added new compset COMPSETNAME, | ||
+ | |||
+ | Examples 2: | ||
+ | Added new diagnostics in cloud.F90, bit identical compared to revision r | ||
+ | |||
+ | ==== What should be stated in the copy message of a branch? ==== | ||
+ | |||
+ | A more elaborated " | ||
+ | |||
+ | ==== What should be stated in the copy message of a tag? ==== | ||
+ | |||
+ | Ideally, the commit message of a tag should provide a complete change history relative to the last tag. This information can be easily extracted from the svn viewer. | ||
+ | |||
+ | Example 1: | ||
+ | < | ||
+ | Change history: trunk-2.0 -> trunk-2.1 (r190 -> r198) | ||
+ | |||
+ | Revision 198 | ||
+ | |||
+ | | ||
+ | |||
+ | Revision 193 | ||
+ | |||
+ | | ||
+ | |||
+ | Revision 190 | ||
+ | |||
+ | | ||
+ | </ | ||
+ | |||
+ | Example 2: | ||
+ | < | ||
+ | Change history: trunk-2.3 -> featureMicomDevelopment-1 (r200 -> r205) | ||
+ | |||
+ | Revision 205 | ||
+ | |||
+ | | ||
+ | |||
+ | Revision 202 | ||
+ | |||
+ | changes made in r202 to branch featureMicomDevelopment... | ||
- | In this case, create a new branch: " | + | Revision 200 |
- | You have to consider the following: Do you want to create a new " | + | changes made in r200 to branch featureMicomDevelopment... |
+ | </ |