Environment setup

With the setup described here, you will have one copy of the EC-Earth 4 code ready for development. This setup, with references to two Gitlab remotes, is needed once only.

Prerequisites

We assume a minimum knowledge of git. If you are unfamiliar with it, have a look at these resources:
- software carpentry beginner lessons
You should have registered for an account on the SMHI gitlab instance. See Getting access to the development platform.
Finally, a recent version of Git is recommended. Versions older than 2.14 miss some features related to submodule. You can check the Git version with:
```
>>> git --version
git version 2.25.1
```
Check with your administrator if you need to upgrade.

Setup the superproject

Get a copy of the EC-Earth 4 project

This step is needed if you did not go through the Getting the source code and are starting from scratch. Then you clone the repository with:

git clone -o upstream --recurse-submodules https://git.smhi.se/ec-earth/ecearth4.git

You will see a lot of output on the screen. Version numbers may differ according to the project advancement, but it should look like:

>>> git clone -o upstream --recurse-submodules https://git.smhi.se/ec-earth/ecearth4.git
Cloning into 'ecearth4'...
Username for 'https://git.smhi.se': XXXX
Password for 'https://sager@git.smhi.se':
remote: Enumerating objects: 698, done.
remote: Total 698 (delta 0), reused 0 (delta 0), pack-reused 698
Receiving objects: 100% (698/698), 1.87 MiB | 4.73 MiB/s, done.
Resolving deltas: 100% (337/337), done.
[...]
Submodule path 'sources/nemo-4.2': checked out '68e39f70a8e32452e7fc480f17c36ff6ad3d092a'
Submodule path 'sources/oasis3-mct-5.0': checked out 'b9ea055f25bbff466acbe46e72bb4f88763f8498'
Submodule path 'sources/oifs-43r3v2': checked out '27d3451306d4e2757016494e8e9a150df4d7f691'
Submodule path 'sources/xios-2.5+': checked out 'cddb36170c6d8001fbfdb9dc8301e27fac8e966e'

Note the submodules listed at the end. They correspond to the components of EC-Earth that have their own repository. Some extra steps (see next section) are required to contribute to their development. But not all components have a dedicated repository. Currently only NEMO, OpenIFS, OASIS3-MCT and XIOS do.

Hint

Please have a look at the hint given in Getting the source code, regarding the time it takes to download the complete EC-Earth 4 repository with submodules.

Fork the EC-Earth 4 project

To share your work, you will need a fork of the project on GitLab. Go to https://git.smhi.se/ec-earth/ecearth4. Click on the fork button (top right). You will be asked to “Select a namespace” for the project URL: choose your name in the drop down list, and click on “Fork project”.

To allow your colleagues to see your changes to the code, you will need to open up the permissions of the fork. This can be done for individual users or for the full ecearth group.

You will end up with your own project: https://git.smhi.se/YOURNAMESPACE/ecearth4, where YOURNAMESPACE is your user name in GitLab. You need to add a reference to it in your local copy of the code:
```
cd ecearth4
git remote add origin https://git.smhi.se/YOURNAMESPACE/ecearth4.git
```
Finally, get up-to-date repositories references:
```
git fetch --all
```
You can double-check that the two remotes are correctly set with:
```
>>> git remote -v
origin     https://git.smhi.se/YOURNAMESPACE/ecearth4.git (fetch)
origin     https://git.smhi.se/YOURNAMESPACE/ecearth4.git (push)
upstream   https://git.smhi.se/ec-earth/ecearth4.git (fetch)
upstream   https://git.smhi.se/ec-earth/ecearth4.git (push)
```

Setup a submodule

Let’s now assume that you want to modify the OpenIFS code. You first navigate to its directory:

cd ecearth4/sources/oifs-43r3v2

and then retrieve information about its remote:

git remote -v

It should read:

origin  https://git.smhi.se/ec-earth/vendor/openifs/oifs43r3.git (fetch)
origin  https://git.smhi.se/ec-earth/vendor/openifs/oifs43r3.git (push)

This output indicates the project page: https://git.smhi.se/ec-earth/vendor/openifs/oifs43r3. The page can also be found by navigating to the “sources” directory in the web interface:

Clicking on the component name will bring you directly to its project page.

Visit that project page and fork the OpenIFS project in the same way you forked the EC-Earth 4 project. You should now own a second project: <https://git.smhi.se/YOURNAMESPACE/oifs43r3>.

Finally, configure the component repository:

cd ecearth4/sources/oifs-43r3v2    #if not there already
git remote rename origin upstream
git remote add origin https://git.smhi.se/YOURNAMESPACE/oifs43r3.git
git fetch --all

Note

To summarize, you have:

forked the EC-Earth 4 and the OpenIFS repositories
setup your local copy of EC-Earth 4 with references to your (as origin) and the reference (as upstream) repositories