Newer
Older
************************************************
Contributing to the NEMO reference code
************************************************
.. contents::
:local:
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
=================================================
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
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.
.. _NEMO Long Term Development Strategy: https://doi.org/10.5281/zenodo.7361464
.. _Working Group contact: https://forge.nemo-ocean.eu/nemo/nemo/-/wikis/working-groups
.. _NEMO System Team: https://www.nemo-ocean.eu/consortium/team/
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.
.. _NEMO Annual Work Plan: https://forge.nemo-ocean.eu/nemo/nemo/-/wikis/2023%20Work%20Plan
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.
.. _NEMO Ocean Engine Reference Manual: https://doi.org/10.5281/zenodo.8167700
.. _module_example.F90: https://forge.nemo-ocean.eu/nemo/nemo/-/blob/branch_4.2/src/OCE/module_example.F90
Step 4: Access to the NEMO Forge
==================================================================
* Register as a user on the `NEMO Forge`_
.. image:: _static/Ext_dev_registerforge.png
:align: center
:width: 90%
.. _NEMO Forge: https://forge.nemo-ocean.eu/nemo
|
* 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
.. _Authy: https://authy.com/
* 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.
.. _External Contributors fork: https://forge.nemo-ocean.eu/extdevs
Next you need to request developer access to the `External Contributors fork`_
.. image:: _static/Ext_dev_exploreprojects.png
:align: center
:width: 90%
|
.. image:: _static/Ext_dev_exploreallprojects.png
:align: center
:width: 90%
|
.. image:: _static/Ext_dev_findextdev.png
:align: center
:width: 90%
|
.. image:: _static/Ext_dev_requestaccess.png
:align: center
:width: 90%
|
* Link with your local machine using an SSH key
To generate an ssh key on the machine that you work on:
.. code-block:: bash
ssh-keygen -t ed25519
Then copy the public key to your account on the NEMO Forge under your profile preferences
.. image:: _static/Ext_dev_profilepreferences.png
:align: center
:width: 90%
|
.. image:: _static/Ext_dev_addsshkey.png
:align: center
:width: 90%
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
.. image:: _static/Ext_dev_createissue.png
:align: center
:width: 90%
|
Here is an example of an issue that was created to test this procedure:
.. image:: _static/Ext_dev_createissue2.png
:align: center
:width: 90%
|
* Create a branch corresponding to this issue
On your local machine clone the external contributor repository:
.. code-block:: bash
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
.. code-block:: bash
git branch 7-the-name-of-your-branch
git switch 7-the-name-of-your-branch
git push -u origin 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)
.. code-block:: bash
git branch -a
* Push your changes back to the forge for savekeeping
.. code-block:: bash
git add path/fileyouchanged.F90
git commit -m 'add comments about the changes'
git push origin
* To update your local repository with changes make on the remote repository to your branch (perhaps by a collaborator or yourself on a different machine) use the fetch command:
.. code-block:: bash
git fetch
Note that this fetches the updates but does not yet merge them. You can then review the differences:
.. code-block:: bash
git diff
If you are happy, you can then merge these changes into your local repository:
.. code-block:: bash
git merge
Any changes you have made in your local workspace will be preserved until you commit them, so you wont risk overwriting something you have recently edited by following these steps.
* If, however, you want to totally reset your local branch to that stored on the remote repository:
.. code-block:: bash
git reset --hard origin/<branch_name>
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 fork (which is essentially a mirror of the continiously evolving NEMO reference).
First you should try to rebase your branch and resolve any conflicts.
.. code-block:: bash
git rebase main
The idea here is that the changes that took place on the main while you were undertaking your developments are now moved to your branch giving the impression that your branch just started from the head of the main. This is a clean approach and helps with reviewing.
Alternatively you can merge the main into your branch. This is a less desirable approach as it essentially adds all the developments that took place on the main to your own branch's history
.. code-block:: bash
git merge main
Once once this step has been completed can you finalize and proceed with a merge request.
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.
.. _SETTE: https://sites.nemo-ocean.io/user-guide/sette.html
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
.. image:: _static/Ext_dev_createmergerequest.png
:align: center
:width: 90%
|
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.
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`_.
.. _NEMO Discourse group: https://nemo-ocean.discourse.group
