Participating in the Development Process

This page is Under Development

---

In order to make changes to either the UFS-S2S-model repository or one of the component repositories, a developer will need to have a fork and a branch from which to create a pull request. The process will be outlined for the simplest scenario, a change to a single component repository, to help illustrate the steps involved.

Developer Jane Doe (github username JaneDoe) wants to fix a bug in the CICE5 repository which is used within the UFS-S2S-model. To accomplish this, she needs a fork of both CICE5 and the UFS-S2S-model.

1. Following the basic github instructions for Working with Forks, Jane Doe forks both repositories.

2. After cloning her fork of the UFS-S2S-model into a working area WORK, Jane Doe creates a branch of UFS-S2S which will contain her bugfix branch for the CICE component.

git clone git@github.com:JaneDoe/ufs-s2s-model.git WORK
cd WORK
git submodule update --init --recursive
git checkout -b bugfix/s2s_with_CICEbugfix

3. Jane Doe then needs to pull her fork of CICE5 into her cloned UFS-S2S repository:

 cd CICE_SRC
 git remote add JD https://github.com/JaneDoe/CICE5.git
 git fetch JD
 git checkout -b bugfix/CICEbugfix

then update the ~/WORK/.gitmodules to point to her fork of CICE5 where her bugfix branch resides:

[submodule "CICE_SRC"]
        path = CICE_SRC
        url = https://github.com/JaneDoe/CICE5.git
        branch = develop

And then sync the submodules at the top of the UFS-S2S checkout:

cd ~/WORK
git submodule sync

4. At this point, git status will reveal that both .gitmodules and CICE_SRC have been modified:

	modified:   .gitmodules
	modified:   CICE_SRC (new commits)

Committing these changes should result in a new branch in Jane Doe's UFS-S2S-model fork which points to her bugfix branch of CICE in her CICE fork. Note: At this point, it is often a good idea to double-check the hashes and even do a test checkout to ensure that the bugfix/s2s_with_CICEbugfix clones correctly.

5. Jane Doe must then test and ensure that the CICE5 branch bugfix/CICEbugfix is working as intended within the UFS-S2S-model (ie, bugfix/s2s_with_CICEbugfix), run the regression tests and commit the logs showing that the tests either pass or fail. In the case of a bugfix, the tests will most likely fail.

6. Once testing is completed, Jane Doe needs to create an issue on the CICE5 repository which explains the bug and how the bugfix was made.

7. Jane Doe then issues a pull request from her CICE5 fork to the NOAA-EMC repository for her branch bugfix/CICEbugfix. When the Pull Request is made, it should reference the issue created at step 6. This can be done automatically by entering the # symbol and waiting for the associated issues to populate the pop up. In the text, JaneDoe should briefly describe the code changes made and whether the changes change any baseline result.

8. When notified of the Pull Request, the code managers for the CICE5 repo will perform the review and commit to the develop branch.

9. Once the develop branch of CICE5 has been updated, the process needs to be repeated at the UFS-S2S-model level (issue creation, PR request, review and commit).

Additional considerations

Note that each component or UFS repository will most likely have their own tests or procedures that are required. For example, for the NEMS repository, changes must pass the regression tests for all supported apps. Changes to the fv3atm repository for UFS-S2S-model must also pass the regression tests for ufs-weather-model.

Also, when a developer is proposing an added feature, they will be asked to create a regression test for that feature which "exercises" the new feature. They will also need to demonstrate that, when optioned off, the feature does not change the model baseline.