UPP Code Development

Code Managers

• NCEP production suite implementation branches - develop, master, release/gefs(gfs)*:
  Wen Meng ([email protected]), Hui-ya Chuang ([email protected])
• UFS release branch - release/public-v*:
  Fernando Andrade-Maldonado ([email protected]), Wen Meng([email protected])
• HWRF implementation branch - HWRF:
  Zhan Zhang ([email protected]), Bin Liu ([email protected])

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 [email protected]:your_github_account/UPP.git 
   >git remote add upstream [email protected]: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.

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

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 ([email protected]) or Hui-ya Chuang ([email protected]) 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 [email protected]:your_github_account/UPP.git 
   >git remote add upstream [email protected]: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).

7. Run the UPP regression tests on at least one of the UPP-supported platform (i.e., WCOSS2, Hera, Orion).

   • If you have access to NOAA's Hera system, developers have the option to use the DTC regression testing framework for additional testing; this may be requested by code managers as well. This is currently only available for changes proposed to the develop branch or any new release/public* branches. Contact branch code manager for questions.

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

9. 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.

10. After your pull request is merged into the original repository, delete your feature branch. You may repeat steps 4-10 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 board in the Q&A section.

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.