Participating in the Development Process

This page is Under Construction

---

Within the ufs-s2s-model, only a single develop branch is currently maintained. Therefore, 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 basic process of creating and maintaining a fork is explained here and is the same whether you are forking the ufs-s2s-model or forking a component repository.

A pull request relating to a single component repository

Developer Jane Smith (github username JaneSmith) has been working with the ufs-s2s-model and finds bug in source code of the CICE5 repository.

Jane should create an issue on the ufs-s2s-model repo and the cice5 repo itself to notify the code managers that she has identified a bug, including a brief description of the bug and (if known) a way to fix it. Creating an issue alerts the code managers to possible incoming commits and helps them plan their commit schedule. It also alerts other users of ufs-s2s-model of the bug and allows them to also work on fixing it.

Creating the required forks and branches

1. If she has not already done so, Jane will need to create a personal fork of both CICE5 and ufs-s2s-model.

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

git clone [email protected]:JaneSmith/ufs-s2s-model.git WORK
cd WORK
git submodule update --init --recursive
git checkout -b bugfix/s2s_with_CICEbugfix

3. Jane then needs to pull her fork of CICE5 into her cloned ufs-s2s repository:

 cd CICE_SRC
 git remote add JS https://github.com/JaneSmith/CICE5.git
 git fetch JS
 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/JaneSmith/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 Smith'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.

Testing the bugfix (under construction)

Making a Pull Request and Committing the fix (under construction)

1. When all required testing is complete, Jane 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 for the bugfix. This can be done automatically by entering the # symbol and waiting for the associated issues to populate the pop up.

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

3. Once the develop branch of CICE5 has been updated, Jane will need to repeat the process 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.