Contributing to the NEMO reference code

Introduction

As an expert user, you may wish to feed some of your developments back into the NEMO reference code and therby become an “external contributor”. This could be an attractive opportunity to ensure the long term use of your work and your efforts will be recognised as you will become a co-author on the next NEMO official release.

It is important to note that due to the large user base and variety of applications of NEMO, the reliability of the code is paramount and thus standards must me met.

To ensure that the candidate external developer has all the tools necessary to make a valuable contribution to NEMO, the following protocol has been put in place.

Note that the effort required to prepare a development for distribution within the NEMO reference code is much larger than simply writing/adapting code for your own personal use. Before proceeding, we suggest that you reflect on how much time you are willing to dedicate to this task and discuss it with your line manager. That said, if you do decide to proceed and are motivated to meet the required standards, your will be rewarded by your work having longevity and community accreditation.

Step 1: Approval from relevant Working Group

The NEMO Long Term Development Strategy is organised into chapters authored by Working Groups. These are collections of experts on topics that are viewed as being of particular importance to current and future NEMO developments. Before gaining privileged access to the NEMO forge, it is important that you run your development past the Working Group leader that is most revelant to your area of interest. This will enable you to get feedback on your proposed development or allow you to adapt/improve your existing development to be in line with NEMO requirements.

We advise that you refer to the NEMO Long Term Development Strategy to identify the correct Working Group contact, and send the relevant person a short note describing your development.

Once your development has been determined by the Working Group as being of value to NEMO, you will then be put in contact with a memeber of the NEMO System Team who has expertise in your area of interest.

Step 2: Addition of your development to the Annual Work Plan

The NEMO Annual Work Plan is a document used by the System Team to coordinate developments expected to take place during a calendar year. Once your development has been approved in theory by your Working Group leader, and you have discussed it with the NEMO System Team contact assigned to you, your task will be added to this document.

Step 3: Following NEMO development Standards

As mentioned previously, the reliability and readability of the NEMO reference code is of utmost importance to developers and users alike. As such, it is vital that you refer to the chapter on “Coding Rules” in the the NEMO Ocean Engine Reference Manual, and the module_example.F90 template for coding in Fortran for NEMO. If your development does not comply with these standards, it will not be included in the NEMO reference.

Step 4: Access to the NEMO Forge

• Register as a user on the NEMO Forge

• Double authentication is required for all access to the forge. Please download an auth app with your mobile phone, e.g. Authy, and link with the NEMO forge by scanning the QR code

• An External Contributors fork of the evolving NEMO main has been created to provide a space for candidate developments not made by the official members of the NEMO System Team. This fork is updated with the main at regular intervals and so the purpose is not to merge your developments to this fork, but to use this space as a sandbox for testing and validation before your branch is transferred across to the NEMO main.

Next you need to request developer access to the External Contributors fork

• Link with your local machine using an SSH key

To generate an ssh key on the machine that you work on:

ssh-keygen -t ed25519

Then copy the public key to your account on the NEMO Forge under your profile preferences

Step 5: Your own branch on the NEMO External Contributors fork

Under the External Contributors fork, you can now create your own branch of NEMO and implement your planned developments.

• Create an issue

Here is an example of an issue that was created to test this procedure:

• Create a branch corresponding to this issue

On your local machine clone the external contributor repository:

git clone git@forge.nemo-ocean.eu:extdevs/nemo.git nemo
cd nemo

Now create a branch starting with the number that corresponds to the issue you created. In the above example it created issue number 7

git branch Fork-7-the-name-of-your-branch
git switch Fork-7-the-name-of-your-branch
git push -u origin Fork-7-the-name-of-your-branch

You now have an issue and branch that are linked and can proceed with your developments.

Step 6: Make changes to your branch on your local machine

• Make sure that you are in the right branch (yours should be green with an asterix next to it)

git branch -a

• Stage your changes

git add path/fileyouchanged.F90
git commit -m 'add comments about the changes'

Step 7: Bring your branch up to date with the main

Before you create a merge request you need to bring your branch up to date with the main of the NEMO reference by following these steps:

1. Verify that the External Contributor fork is up to date. If you do not have the access right to update the fork, ask your NEMO System Team contact to do so for you:

2. Update your local copy of the fork main:

git switch main
git pull

3. Merge the main into your branch

git switch X-the-name-of-your-branch
git merge main

Note

If you have touched a past of the code that has simultaneously been edited by another developer, you will have the following message pop up:

CONFLICT: Merge conflict in filename.F90
Automatic merge failed: fix conflicts and then commit the result.

4. Resolve conflicts if necessary by opening your file and accepting or rejecting the changes pointed out by “HEAD” meaning the head of your branch and “main” meaning the fork’s main, arrows <<<<<<< and >>>>>>> show where lines have been removed or added.

Then add your changed files

git add filename.F90
git commit -m 'fix conflicts'

5. Once you have resolved these conflicts you can push:

git push

Caution

If your branch is out of date with that stored on the Forge (due to changes made by yourself on another machine or contributions from a collaborator), you can totally reset your local branch:

git reset --hard origin/<branch_name>

Step 8: Test your branch using SETTE

SETTE is a suite of bash scripts that automates the building, running and basic validation and verification of a broad spectrum of NEMO reference and test configurations. This test checks for restartability and reproducibility of a set of reference configurations and outputs the sucesses or failiures of each test.

Your development will be required to pass SETTE before it goes to review.

Your NEMO System Team contact will help you launch the SETTE tests so please contact them at this stage for advice.

Step 9: Create a merge request

Once your developments have been tested and shown to not “break the code”, you are ready to merge and can follow the steps below to create a merge request

Here you can assign a reviewer (your designated NEMO System Team contact person) and give a description of the work that you did to aid the review process.

Once this merge is accepted, you developments will be added to the NEMO reference code. Please then go and close your issue on the External Contributor fork so that it is clear that this development is no longer outstanding.

Step 10: Update of documentation and development included in the NEMO reference

The last step in your journey is to update the NEMO documentation so that a description of your development is available to other users and your contribution can be recognised by the community.

To do this, you will need to liase with your NEMO System Team contact person who will assist you in adding a section in the relevant NEMO reference manual (Ocean Dynamics, Sea Ice or Biogeochemistry).

Your work will now be ported across into the NEMO reference code and you will be cited as co-author in the documentation of the next official release!

The NEMO Forum for Q&A

Chatting with other users and developers and sending feedback is a useful way to contribute to NEMO efficency and reliability. For this, you can join the NEMO Discourse group.