Contributing to the NEMO reference code
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.
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.
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.
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.
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.
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
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 email@example.com: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.
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'
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:
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:
Update your local copy of the fork main:
git switch main git pull
Merge the main into your branch
git switch X-the-name-of-your-branch git merge main
CONFLICT: Merge conflict in filename.F90 Automatic merge failed: fix conflicts and then commit the result.
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'
Once you have resolved these conflicts you can push:
git reset --hard origin/<branch_name>
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.
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.
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!
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.