Daily work

Create an issue in GitLab

If the work you’re planning to do in your branch does not address an existing issue, consider creating one in the main project page. This gives you an opportunity to describe what you’re planning to do and it creates a space to discuss and document any progress and to get feedback.

Create branches

New lines of development are carried out in dedicated branches. In most cases you will branch off the stable main branch from the upstream remote. Decide on a meaningful name (here called MYBRANCH) and create branches in the superproject and in the component your are about to modify.

First in the EC-Earth superproject:

cd ecearth4
git checkout -b MYBRANCH upstream/main
git submodule update --recursive

Then in the submodule. Continuing with the OpenIFS example:

cd ecearth4/sources/oifs-43r3v2
git checkout -b MYBRANCH upstream/main

Development

Once your branches are setup, you can start editing the source code to implement your feature or bug fixes. Test and debug as needed. You will likely record intermediate steps in you repositories, which is detailed in the next section.

Stage and commit your changes

Always start FIRST with the submodules if they have been modified:

cd ecearth4/sources/oifs-43r3v2
git add FILENAMES-TO-COMMIT
git commit -m "A nice but not too long (max 60) commit message"

This can be repeated as often as needed. If you want to add more information to the commit message, you can use a file with -F file instead of -m message, where you leave a blank line between the title (1st line) and the rest of your message.

Once you are done committing in your component, you can move to the EC-Earth 4 project and check its status:

cd ecearth4
git status

will show that the submodule has been modified (the branch name is sandbox in this example):

[2037] (sandbox *) >>> git status
On branch sandbox
Changes not staged for commit:
(use "git add <file>..." to update what will be committed)
(use "git restore <file>..." to discard changes in working directory)

           modified:   sources/oifs-43r3v2 (new commits)

Stage and commit the submodule change detected by the main project:

git add sources/oifs-43r3v2/
git commit -m "Record very interesting recent commits in oifs"

Other regular changes outside the submodules are dealt with as usual. For example, a new file:

[2041] (sandbox %) >>> git status
On branch sandbox
Untracked files:
  (use "git add <file>..." to include in what will be committed)

        runtime/classic/THIS-DIR-IS-NOT-USED-ANYMORE

can be added to the local repository with:

git add runtime/classic/THIS-DIR-IS-NOT-USED-ANYMORE
git commit -m "Add a warning file"

Create Merge Requests

Once your branches are matured and ready to be merged into the main project, you will create merge requests (MR). Again, start with the modified components if any:

Visit your component project page https://git.smhi.se/YOURNAMESPACE/oifs43r3
Click on “Merge requests” on the left panel
Then on the “New merge request” in the middle of the page
You’ll see a page like this:

For the source, choose your branch. For the target, the original project you forked should be proposed and the branch should be main. The last commit of both source and target is shown:
Click on “Compare branches and continue”. Add a title, description, assignee, etc… and when ready click on “Create merge request”. Note the MR number. It starts with an exclamation mark (eg: !23).
Repeat the procedure and create a MR in your EC-Earth superproject web page: https://git.smhi.se/YOURNAMESPACE/ecearth4. If you have created a MR in one of the submodule, you can refer to it in your MR description and/or title. For example with:
```
This (EC-Earth) MR extends functionality Y. For this, it makes use of
the new feature X in OpenIFS, see ec-earth/vendor/openifs/oifs43r3!23
```

Cleaning up

Removing old branch

Once the MRs have been merged, you should remove the branch and start afresh. Starting with the modified component:

cd ecearth4/sources/oifs-43r3v2
git checkout main  #any branch is fine, as long as it is not MYBRANCH
git branch -d MYBRANCH

You should also remove the branch in GitLab, either through the web interface or by entering:

git push origin --delete MYBRANCH

Then repeat the same calls in the EC-Earth 4 project:

cd ecearth4
git checkout main      #any branch is fine, as long as it is not MYBRANCH
git submodule update --recursive
git branch -d MYBRANCH

You should also remove the branch in GitLab, either through the web interface or by entering:

git push origin --delete MYBRANCH

Updating your main branches

Before starting some new development, it is also recommended to get the latest update from upstream:

cd ecearth4
git fetch --all    #or: 'git remote update' if you prefer
git checkout main
git merge --ff-only upstream/main
git push origin HEAD
git submodule update --init --recursive

You should be ready to create new branches starting from the latest stable point of the ecearth4 project.

If you want to also update your submodule fork, follow these steps (continuing with our OpenIFS example):

cd ecearth4/sources/oifs-43r3v2
git fetch --all    #or: 'git remote update' if you prefer
git checkout main
git merge --ff-only upstream/main
git push origin HEAD

Note that if you are not planning to modify the submodule anymore you should set it back to the commit recorded in ecearth4:

cd ecearth4
git submodule update --recursive

Advance settings

You may have noticed that you always push your local branch to a branch with the same name in your fork (origin):

git push origin HEAD

If you set:

cd ecearth4
git config remote.pushdefault origin
# and
cd ecearth4/sources/oifs-43r3v2
git config remote.pushdefault origin

you can just type:

git push

This setting affects only branches with an upstream branch in the upstream remote (see Create branches). If you create a branch with:

cd ecearth4
git checkout -b MYBRANCH origin/somebranch

a simple call to git push will complain. To make it work, you need to set:

cd ecearth4
git config push.default current