UPP Code Development

On This Page

• Code Managers
• Contributing Changes to UPP develop
• Contributing Changes to Other UPP Branches
• Adding a New Variable in UPP
• Testing Your Changes
• Documenting Your Code
• Troubleshooting

Code Managers

• NCEP production suite implementation branches - develop, master, release/gefs(gfs)*:
  Wen Meng (Wen.Meng@noaa.gov), Hui-ya Chuang (Hui-ya.Chuang@noaa.gov)
• UFS release branch - release/public-v*:
  Fernando Andrade-Maldonado (fernando.andrade-maldonado@noaa.gov), Wen Meng(Wen.Meng@noaa.gov)
• HWRF implementation branch - HWRF:
  Zhan Zhang (zhan.zhang@noaa.gov), Bin Liu (Bin.Liu@noaa.gov)

Contribute Changes to the UPP Main Development Branch (develop)

1. Open a new issue at https://github.com/NOAA-EMC/UPP/issues and briefly document the changes you plan to contribute to UPP code and why they are needed.

2. Create a UPP fork from https://github.com/NOAA-EMC/UPP by following the GitHub documentation on how to fork a repository.

3. Clone your new UPP fork onto your local system and add the authoritative UPP repository as upstream.

   >git clone git@github.com:your_github_account/UPP.git 
   >git remote add upstream git@github.com:NOAA-EMC/UPP.git  
   

4. Under your UPP fork, create a feature branch off the upstream/develop branch.

   >git fetch upstream
   >git checkout upstream/develop
   >git checkout -b your_feature_branch  
   >git push -u origin your_feature_branch  
   

5. Add your changes to the feature branch, commit, and push the changes to your remote repository.

   • See the Doxygen Documentation slides for information on documenting any new variables added to the code.

6. Sync your feature branch with latest changes in the authoritative repository's develop branch.

   • On GitHub: Sync your feature branch using the "Sync fork" button in the web UI.

   • On the command line: Run git pull upstream develop to introduce the latest changes from the develop branch. If there are conflicts, see GitHub's documentation on resolving a merge conflict. Users will need to visit files where there are conflicts and select which changes to keep or discard. For example, users might run:

     > cd my_UPP_clone
     > git remote add upstream git@github.com:NOAA-EMC/UPP.git
     > git fetch upstream
     > git merge upstream/develop
       **manually solve conflicts
     > git submodule update --init --recursive
       **use `git add` and `git commit` commands to save changes
     > git push -u origin my_branch
     

7. Run the UPP regression tests on one of the UPP's supported platforms (i.e., WCOSS2, Hera, Orion, Hercules).

8. Create a pull request to submit the changes from your feature branch to the develop branch of the UPP authoritative repository.

9. Notify UPP code manager Wen Meng (wen.meng@noaa.gov) or Hui-ya Chuang (hui-ya.chuang@noaa.gov) for your pull request. They will run the UPP regression tests and merge your changes into the develop branch of the original authoritative repository.

10. After your pull request is merged into the authoritative repository, delete your feature branch. You may repeat steps 4-10 to add additional UPP developments.

Contribute Changes to Other UPP Branches

Changes may be proposed to any release/public* branch that is in active development. Bug fixes may also be proposed to branches already frozen, and code managers will help determine the appropriate action. Developers should contact the branch code manager (see above) for questions and assistance.

Procedures are similar to those for the develop branch above but include key changes to the name of the branch cloned and tests required to ensure platform portability.

1. Open a new issue at https://github.com/NOAA-EMC/UPP/issues and briefly document the changes you plan to contribute to UPP code and why they are needed.

2. Create a UPP fork from https://github.com/NOAA-EMC/UPP by following the GitHub documentation on how to fork a repository.

3. Clone your new UPP fork onto your local system and add the authoritative UPP repository as upstream.

   >git clone git@github.com:your_github_account/UPP.git 
   >git remote add upstream git@github.com:NOAA-EMC/UPP.git  
   

4. Under your UPP fork, create a feature branch off the branch you plan to work with (e.g., release/public-v3, release/upp_v11.0.0). This example will use release/public-v3.

   >git checkout release/public-v3
   >git checkout -b your_feature_branch  
   >git push -u origin your_feature_branch  
   

5. Add your changes to the feature branch, commit, and push the changes to your remote repository.

   • See the Doxygen Documentation slides for information on documenting any new variables added to the code.

6. Sync your feature branch with latest changes in the authoritative repository's corresponding branch (e.g., release/public-v3).

   • On GitHub: Sync your feature branch using the "Sync fork" button in the web UI.

   • On the command line: Run git pull upstream branchname (where branchname is replaced with the name of your branch) to introduce the latest changes from the desired UPP branch. If there are conflicts, see GitHub's documentation on resolving a merge conflict. Users will need to visit files where there are conflicts and select which changes to keep or discard. For example, users might run:

     > cd my_UPP_clone
     > git remote add upstream git@github.com:NOAA-EMC/UPP.git
     > git fetch upstream
     > git merge upstream/release/public-v3
       **manually solve conflicts
     > git submodule update --init --recursive
       **use `git add` and `git commit` commands to save desired changes
     > git push -u origin my_branch
     

7. Create a pull request to submit the changes from your feature branch to the relevant branch of the UPP authoritative repository.

8. Add the branch code manager (see list above) as a Reviewer on your PR. This will notify the UPP code manager of your pull request. They will run the UPP regression tests and merge your changes into the branch in the authoritative UPP repository.

9. After your pull request is merged into the original repository, delete your feature branch. You may repeat steps 4-9 for any future development.

Typically, changes incorporated directly into the release/public* branches will be merged into the develop branch by code managers after the public release. If a change is considered an essential bug fix needed in the develop branch as well, code managers will work with the developer to facilitate that process.

Adding a New Variable in UPP

Please see the UPP User's Guide chapter on Adding a New Variable for instructions. Requests for help with adding new variables can posted on the UPP GitHub Discussions forum in the Q&A section.

Testing Your Changes

The UPP team runs regression tests on all pull requests to ensure that new code changes do not alter results (or that if they do alter results, such changes are reasonable and expected). These tests are run on WCOSS2, Hera, Orion, and Hercules. More platforms may be added in the future. The User's Guide contains instructions on how to run regression tests. Developers are encouraged to run the tests on supported platforms before opening a PR.

Documenting Your Code

The UPP uses Doxygen to build scientific documentation for the code base. Developers are expected to include a Doxygen-styled comment line for any new variables they add to a file. See the Doxygen Documentation slides for information on documenting any new variables added to the code. NOTE: Developers are only responsible for the variables they add to the code and do not need to provide documentation for already-existing but undocumented variables added by others. Fully documenting the UPP is a work in progress, and contributions to this end are welcome but not required.

Troubleshooting

View the list of NetCDF error codes as a starting point when trying to troubleshoot nondescript error messages.