Developers guide

Developers Guide / How to Contribute

MOM6 is an open source project. This means that it relies on a global community of users and developers to maintain and improve the model. It is licenced under the GPLv3. If you use MOM6 and find anything that needs fixing, or make changes that you think could be useful to others, please contribute to the source code.

MOM6 uses Github to manage collaboration. If you are not familiar with GitHub, don't worry, there's lots of excellent documentation out there. For example these guides, in particular contributing to an open source project is explained here. Please read through this before continuing, it will make it a lot easier to understand the terminology.

How to update this wiki

TBC.

Setting up your code repositories

Collaborators

If you do NOT have write access to the CommerceGov repositories and you want to be able to push your own changes to MOM6-examples (or MOM6, SIS2, FMS) source code up to GitHub then you'll need to fork one or more NOAA-GFDL-MOM6-* repositories. For example, if you want to make changes to MOM6-examples, then take the following steps.

Click on "Fork" (near the top-right) of this link to NOAA-GFDL-MOM6-examples on GitHub, select your GitHub account.
GitHub will take you to your own fork which will be at a different URL of the form https://github.com/<your_github_account_here>/NOAA-GFDL-MOM6-examples. On the right side, you will see either "HTTPS clone URL" or "SSH clone URL". Select "SSH" and then copy the URL.
Use the URL from above to clone your forked repository with

git clone --recursive git@github.com:<your_github_account_here>/NOAA-GFDL-MOM6-examples.git MOM6-examples

You will now have a local copy of your own fork of the MOM6-examples repository. However the MOM6, SIS2 and FMS sub-modules will still point to the CommerceGov versions. If you wish to make changes to any of these then you'll have to fork those also, as above. And Once this is done setup a link to them within MOM6-examples using

cd src/MOM6
git remote set-url origin git@github.com:<your_github_account_here>/NOAA-GFDL-MOM6.git

Then update with:

git checkout master
git pull

You can use any combination of CommerceGov and personal repositories as submodules within MOM6-examples.

NOAA employees and contractors

If you have write access to the CommerceGov/NOAA-GFDL-* repositories then simply:

git clone --recursive git@github.com:CommerceGov/NOAA-GFDL-MOM6-examples.git MOM6-examples

When you do this, the sub-modules under MOM-examples will be in detached states pointing to a specific version for each sub-module. This is important and powerful; these particular versions on MOM6 and SIS2 are what were used to obtain the regression tests in MOM6-examples. It means whenever an end-user clones the repository (or updates) they automatically get the correct version of each sub-module.

However, as a developer you will probably want to edit code in the sub-modules and since the sub-modules have specific versions checked out, you will need to checkout a branch instead. Type:

(cd src/MOM6; git checkout dev/master)
(cd src/SIS2; git checkout dev/master)

Under most circumstances, a git status in MOM6-examples will reveal that nothing appears to have changed. That is because the HEAD of dev/master on all repositories are in sync and consistent with those recorded in MOM6-examples. If you ever issue a git submodule update then the submodule(s) will be reset to the appropriate detached state.

Further explanation

By way of explanation, the "recursive clone" in the previous sections is equivalent to the follow steps:

git clone git@github.com:CommerceGov/NOAA-GFDL-MOM6-examples.git MOM6-examples
cd MOM6-examples
git submodule init
git submodule update

where the last line in turn is equivalent to

git submodule update src/FMS
git submodule update src/MOM6
git submodule update src/SIS2
git submodule update tools/matlab/gtools
git submodule update tools/python/025gridGeneration/MIDAS

Knowing this, you can avoid downloading various of the submodules. For instance, you could just clone MOM6-examples and none of the submodules by stopping before the git submodule init.

Workflow

Collaborators

As a collaborator it's largely up to you how you manage your own forked repositories. However there's a couple of things that you'll need to know how to do when you want to send your changes back to the main, or 'upstream' repository.

Syncing a fork with the CommerceGov repositories

Imagine that some changes are made to the main (upstream) CommerceGov repository that you would like to incorporate into your fork. You can do this, for example, with MOM-examples:

git remote add upstream git@github.com:CommerceGov/NOAA-GFDL-MOM6-examples.git
git fetch upstream
git merge upstream/master

Creating a pull request

Whether you are working on a branch or a fork, when you have code ready to submit to the core developers to merge onto dev/master you should make a "pull request". This is managed via the github website.

Navigate to your branch (either via the branch tab or the pull down menu in the commits tab).
Click the green icon, , near the top left, with a mouse-over that reads "Compare, review, create pull request".
The next page shows you the change relative to where you start your branch on dev/master.
Click .
Fill out a descriptive but succinct title
In the comment box, please summarize all the commits involved and explain or justify the code changes.
Then click and you are done.

NOAA employees and contractors

There are many combinations of operations a developer might have to enact which in combination can be made more succinct than follows. Here, we have atomized some operations into self-contained steps from which a developer can build more sophisticated operations.