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*:
  Kate Fossell([email protected]), Cam Sherrell ([email protected]), Wen Meng([email protected]
• HWRF implementation branch - HWRF:
  Zhan Zhang([email protected]), Bin Liu([email protected])

Contribute changes in UPP main development branch develop

1. Make your UPP fork from https://github.com/NOAA-EMC/UPP
   See here for how to do it.
2. Under your UPP fork, create a feature branch off the branch "develop" at the authoritative repos.

>git clone [email protected]:your_github_account/UPP.git 
>git remote add upstream [email protected]:NOAA-EMC/UPP.git  
>git remote -v
>git fetch upstream
>git checkout upstream/develop
>git checkout -b your_feature_branch  
>git push -u origin your_feature_branch  

3. Add your changes in the feature branch and commit.
4. Open a new issue at https://github.com/NOAA-EMC/UPP/issues and briefly document your changes.
5. Sync your feature branch with latest changes in branch develop at authoritative repository.
   See here for how to do
6. Run the UPP regression tests on one of UPP supported platforms (WCOSS-Dell, WCOSS-Cray, Hera).
   See here for how to run
7. Use pull request to submit the changes from your feature branch to the branch develop at authoritative repository.
   See here for how do it.
8. 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 branch "develop" at original repository.
9. After your pull request is merged at authoritative repository, delete your feature branch. You may repeat step 2) to 8) for your next development.

Contribute changes in UPP for public UFS application 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 develop branch above, but with key changes to the name of the branch cloned, populating submodules, and additional tests to ensure platform portability.

1. Make you fork the UPP repository from https://github.com/NOAA-EMC/UPP
   See here for how to do it.
2. Under your UPP fork, create a feature branch off the branch "develop" at the original repos.

>git clone -b _branch_name_ [email protected]:your_github_account/UPP.git  
(** can replace git@ with https:// if ssh keys not set up)
>git remote add upstream [email protected]:NOAA-EMC/UPP.git  
>git remote -v
>git fetch upstream
>git checkout upstream/_branch_name_
>git checkout -b _your_feature_branch_  
>git push -u origin _your_feature_branch_  

3. Add your changes in the feature branch and commit.

4. Open a new issue at https://github.com/NOAA-EMC/UPP/issues and briefly document your changes. Please add tags to reflect the nature of the issue and branch it affects.

5. Sync your feature branch with latest changes in the corresponding branch at upstream UPP repository (if needed).
   See here for how to do

6. Run the UPP regression tests at least one UPP supported NOAA platform. See here for how to run. If you do not have access to a NOAA HPC, please contact branch code manager.
   

7. If you have access to NOAA’s Hera or NCAR’s Cheyenne, 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 develop branch or any new release/public* branches to come (none yet as of April 2021). Contact branch code manager for questions.

8. Use pull request to submit the changes from your feature branch to the branch develop at original repository.
   See here for how do it.

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

10. After your pull request is merged at original repository, delete your feature branch. You may repeat step 2) to 8) for your next development.

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

Update your branch at your fork with branch develop at authoritative repository

• Clone your UPP fork

 >git clone [email protected]:your_github_account/UPP.git

• checkout your feature branch

 >git checkout your_branch

• Add upstream and sync

 >git remote add upstream [email protected]:NOAA-EMC/UPP.git   
 >git fetch upstream  
 >git merge upstream/develop  
 >git push origin  

Add a new variable in UPP

Please see here for the user guide of adding a new variable in UPP.

An example of this procedure can be found in the public Users Guide at https://upp.readthedocs.io/en/latest/AddNewVariable.html.
Requests for help with adding new variables can posted on the UPP section of the UFS Forum: https://forums.ufscommunity.org/forum/post-processing