Skip to content

UPP Code Development

Jump to bottom
Joshua Kublnick edited this page Jul 14, 2025 · 55 revisions

On This Page

Code Managers

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.

  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 Benjamin Blake (benjamin.blake@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.

  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 be posted on the UPP GitHub Discussions forum in the Q&A section.

Testing Your Changes

To run the full regression test (RT) suite in preparation for opening a pull request (PR):

  1. Navigate to the local clone of your UPP fork containing the changes you would like to introduce, and run the included RT script within /ci:

    cd /path/to/UPP/ci
nohup ./rt.sh -a <my_account> -r $PWD/rundir -t $PWD/../ &

    where my_account is the name of an account where you have permissions to run jobs. The terminal will print a message like:

    nohup: ignoring input and appending output to ‘nohup.out’

    The user can continue to issue commands in the Terminal while the RTs run in the background.

Note
The time it takes for tests to run is queue-dependent. RTs can take as little as half an hour to run, but on machines with long queue times, it can take several hours to complete the full set of tests.

  1. Check rt.log.<machine>/nohup.out for a short summary of any changes in results. The tests are finished when there are 16 timestamps and a final results summary (e.g., “No changes in test results detected.”).
  • The /work directory generated in UPP/ci contains out.post.<test_name> files, which list output from each test, including any unexpected errors during runtime.
  • The /rundir directory generated within UPP/ci will include test case results, and .diff files located within each test’s directory will outline changes in fields with the current baselines.
  • Confirm expected changes within the run directory .diff files if any are present.
    • Changes in the rap_pe_test case only consisting of field 708 Convective Cloud Layer may be ignored; this is a known bug and will always be present within the WRFPRS.diff file.

Additional Configuration

For repeated regression test runs, users can edit the rt.sh file and disable the specified test cases by changing their respective values to no. Users can disable the build step as well with the same value for the build variable above the tests. Be sure to enable all test cases and build settings and conduct a full RT run in preparation for a pull request so that code managers (CMs) can confirm all changes in results are expected and consistent with the developer’s results.

rt.sh supports additional configuration of the regression tests using the following options:

  • w — specify the work directory for test case job output
  • r — specify the run directory containing baselines and .diff files for result comparison

The following are legacy options and may be ignored by developers: -b, -u, -c, -t.

Attention: NWS has a strict timeline on operational product delivery. Therefore, UPP code managers request developers perform timing and memory usages tests. If your updates outstandingly increase run time or significantly impact memory usage, they may not be approved by UPP code managers.

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 following list of NetCDF error codes as a starting point when trying to troubleshoot nondescript error messages.

Home

Getting Started

Building and Running the UPP

Documentation and User Support

Developer Support

Branching and Release Strategy

Releases

GTG Access

IFI Access

UPP Terms of Use Notice

Clone this wiki locally