Skip to content

Code Management

Jump to bottom
Jessica Meixner edited this page Jul 3, 2024 · 24 revisions

This wiki page describes the code management of this repository.

Checklist for a Code Manager of a Pull Request to develop

The pull request process is documented in this section of our Developer's Guide.

  • Make sure your develop is up to date with the authoritative repository.
  • A pull request will only be reintegrated to the develop branch after passing all tests, unless it has been made by a trusted repository that has followed the regression testing standards fully (make sure to communicate with the developer that the pull request has not gone straight to the develop branch if the case),
    • Regression testing: The full matrix with same y/n options as regtest/bin/matrix_ncep should be completed.
    • Comparing output of Regression Tests: matrix.comp should be used to compare results with the current develop branch.
    • Add the summary output of matrix.comp to the pull request back to the authoritative repository.
    • State which compiler you used to run the regression tests in the PR.
  • Pull requests should be separate for different features or pull requests. (Ie. branches should be single purpose)
  • Look at the code itself to confirm that code is following WW3 standard practices.
  • Make sure GOTOs were not added. Particularly, computed GOTOs will not be allowed back into the develop. An example of a computed GOTO is:
 GO TO (901,902,903) L2

In general we will strongly discourage any additional general GOTOs as if you add one, we have to remove another one from somewhere.

  • All headers of modules and routines have been updated.
  • If a new feature was added, was a new regression test added?
  • Have you updated a module that reads/writes one of the WW3 binary files (*.ww3), i.e: w3iobcmd, w3iogomd, w3iopomd, w3iorsmd, w3iosfmd, w3iotrmd, or w3src4md? If so, and you have changed the format the binary file, then ensure that you update the relevant VERxxx string. This string is located near the top of the module and should be updated to the modification date in "YYYY-MM-DD" format.
  • Are required manual updates included?
  • Should this be a new version number X.XX?
  • Run the full set of the regtests (for example at EMC we use regtests/bin/matrix_ncep to generate the list of tests with information on submitting to queue). To confirm all tests ran without error 'grep -nri error matrix.out' Then, we use matrix.comp (see: How to use matrix.comp to compare regtests with develop) to confirm if answers have changed between the current develop and the tested branch.

Checklist for a Developer Submitting to develop

When you are ready to create a pull request back to develop, make sure the list below has been completed and then send an email to the code manager with the branch name and answer to the questions below:

  • Did you add any GOTOs? Computed GOTOs will not be allowed back into the develop. An example of a computed GOTO is:
 GO TO (901,902,903) L2

but in general, we will strongly discourage any additional general GOTOs as if you add one, we have to remove another one from somewhere.

  • All headers of modules and routines have been updated.
  • Does a new regtest need to be made? If so have you added it and completed Checklist for Adding or Modifying a Regtest
  • Have you updated a module that reads/writes one of the WW3 binary files (*.ww3), i.e: w3iobcmd, w3iogomd, w3iopomd, w3iorsmd, w3iosfmd, w3iotrmd, w3iogrmd, or w3src4md? If so, and you have changed the format the binary file, then ensure that you update the relevant VERxxx string. This string is located near the top of the module and should be updated to the modification date in "YYYY-MM-DD" format.
  • Have you made the required manual updates?
  • Will this correspond to a new version X.XX? If yes, make a comment in your issue indicating that this including information about that the "about" description in the manual page should be.
  • Code managers will run a full set of the regtests (for example at EMC we use regtests/bin/matrix_ncep to generate the list of tests with information on submitting to queue). To confirm all tests ran without error 'grep -nri error matrix.out' then, we use matrix.comp (see: How to use matrix.comp to compare regtests with develop) to confirm if answers have changed between the current develop and the tested branch.

Checklist for Updating Version Number

The version number update is performed by the authoritative repository code manager. The following is the checklist of tasks when updating the version number.

  1. Update any subroutine 7.XX (7.xx, 7.XY, X.YZ, etc.) to correct version number
  2. Update version number in manual/defs.tex and manual/intro/about.tex
  3. Update version number in w3initmd.F90 (WWVER)
  4. Commit message (with correct version number) "Updated version number to 7.XX"
  5. Update milestones page with version number
  6. Update front github page (or anywhere else we are keeping track of the github number, not sure what this is yet)

Checklist for Public Release

The list of tests that will be run before a public release is created is:

Running matrix.base for the following compilers:

  • Intel (defaults in comp.Intel)
  • Intel with debug compiler options and no optimization ( opt="-c $list -O0 -assume byterecl -g -traceback -check all -fpe0 -ftrapuv -module $path_m")
  • Portland (comp.Portland)
  • GNU (comp.Gnu)
  • Run with S T and other debug flags to make sure tests run

Test NCEP operational systems:

  • GFSv16
  • GEFSv12
  • Great Lakes

Branch rules for dev/ufs-weather-model

The dev/ufs-weather-model branch has been created for the UFS so that hot-fixes or coupled model development can be merged into the code that is tested with the ufs-weather-model branch. This branch will be kept in sync to what is used in the ufs-weather-model at all times. This is easier for coupled model users and is meant to facilitate that work.

Developments from WW3 can be reintegrated to the ufs-weather-model in two ways:

The preferred method is to the develop branch, but either are acceptable. If a PR goes to the dev/ufs-weather-model instead, the WW3 code managers will ensure that development goes immediately into the develop branch as well.

Procedure for a PR to the dev/ufs-weather-model branch

When a PR is submitted to dev/ufs-weather-model, code managers of WW3 should:

  1. Make sure there is a corresponding PR in the ufs-weather-model that follows that repos procedures (ie. issues, etc).
  2. Review the PR to make sure the code updates are appropriate and follow WW3 rules. If code changes are in non-wmesmf code, the code managers will run the standalone WW3 regression tests at this time. If there are issues with code, please bring them up now (and do not wait until its almost time to be merged).
  3. This PR is merged to WW3 dev/ufs-weather-model when it's going to be merged into ufs-weather-model. The merging happens after the ufs-weather-model regression testing has been completed for all platforms. The PR should not be approved, unless it meets normal WW3 requirements.
  4. Once the ufs-weather-model regression tests have completed on all platforms, the WW3 code managers will approve the PR on the GitHub interface (note, if any code issues are raised, please bring these issues up before we get to this point).
  5. Merge the PR: Make a squash merge (using the commit message in the PR) to dev/ufs-weather-model after the regression tests of ufs-weather-model have passed.
  6. After merging to dev/ufs-weather-model, the WW3 code managers will then, if appropriate, merge these updates to the develop branch. Note, we expect there to be very few exceptions to the need to not bring changes back to the develop brach. The code-manager will use git-cherry pick to create a PR, preserving proper authorship and commit message or ask the original developer to create this second PR to the develop model. If changes are only in wmesmf, a quick test on a single platform (assuming that the develop branch is ahead of the dev/ufs-weather-model) should be conducted. If other changes are made, the regular WW3 regression tests should be repeated with the develop branch (again assuming the develop branch is ahead of the dev/ufs-weather-model branch, requiring these additional tests).

Syncing the develop branch to dev/ufs-weather-model:

The WW3 code managers will periodically sync development from the develop branch to dev/ufs-weather-model branch. This should be done on a minimum of once a quarter but ideally more frequently and after large developments into the develop branch or when they want to bring in a change to the coupled model.

  1. Create an issue in ufs-weather-model.
  2. Make a new branch from NOAA-EMC dev/ufs-weather-model branch on your fork.
  3. Merge NOAA-EMC develop branch changes to the new branch.
  4. Make a branch of ufs-weather-model pointing to your new branch of WW3. Remembering to:
  • Create new mod_def files, if necessary.
  • Run the wave related ufs-weather-model regression tests on at least one platform
  • If new baselines are needed, create a baseline and make sure you can match this baseline on at least one platform.
  1. Create PR to WW3 from new branch to NOAA-EMC dev/ufs-weather-model branch.
  2. Create a PR to ufs-weather-model
  3. Wait until it's the PR's turn to be committed to ufs-weather-model, making sure to keep your branch in sync and periodically running a wave test to ensure the PR is still working.
  4. After all regression tests for ufs-weather-model are completed for all platforms, merge the WW3 PR to dev/ufs-weather-model. The first choice is to merge using the rebase option, the second is to create a merge commit.
  5. Update the ufs-weather-model branch to point to the dev/ufs-weather-model branch.
  6. ufs-weather-model code managers will commit the PR.

Branch rules for production branches

  • The production branches are created for NCEP production models and are to be kept in sync with what is in production.
  • Code managers should communicate with the wave POC for the production model before merging anything to a production branch.
  • The production branches should be created from the develop branch.
  • While emergency fixes are needed, please be sure to reintegrate any development back to the develop branch (following proper protocols for the develop branch (ie, tested, documented, etc) as soon as possible.
  • Production branches will be restricted and require a PR to merge to them.

Automatic tests update for Github Action

Whenever the spack.yaml changes due to changes in libraries, the CI ends up with an error due to dependencies unless the hash of the spack.yaml in the cache_key variable changes manually (i.e. gnu5 > gnu6).

Quick Links

Clone this wiki locally