Skip to content

Creating a WRF Code Release

Jump to bottom
Kelly Werner edited this page Apr 28, 2022 · 42 revisions

These are the specific instructions for WRF repository administrators to conduct a WRF release.

There are 2 types of releases:

  1. Major release (e.g. V4.0, V4.1): These releases include all new/approved development, along with bug fixes.
  2. Minor release (e.g., V4.0.1, V4.0.2): These releases ONLY include bug fixes.

Creating the release

When all testing is complete and the release committee agrees, the release can be finalized.

  1. Create a pull request to update the top-level README file, and the inc/version_decl file with the correct version and release date. If no one is around to approve this quickly, you will need to modify permissions for the release branch on GitHub. To do so, follow these steps:
    a) go to GitHub.com/wrf-model/WRF
    b) click on settings -> branches -> 'edit' release-v4*
    c) remove protections from all checked boxes
    d) save

Double-check your modified files, and then you can approve and squash/merge your modifications.

  1. Go back to your terminal window and clone the main wrf-model/WRF repository as a new directory.
  • git clone git@github.com:/wrf-model/WRF.git WRF_RELEASE_PREP

NOTE:If you don't have your ssh keys set up for GitHub, you will need to use this syntax:

  • git clone https://github.com:/wrf-model/WRF.git WRF_RELEASE_BRANCH and then 'cd' into that new directory.

Ensure that origin points to the main wrf-model/WRF repository:

  • git remote -v

You should see (This is important, or below commands will not work):

  • origin git@github.com:wrf-model/WRF.git (fetch)
  • origin git@github.com:wrf-model/WRF.git (push)
  1. Locally merge the release branch into master (fetch to ensure your local repository is up to date).
  • git checkout master
  • git merge --no-ff origin/release-v4.X

    You should then have the option to add a comment, such as:

    Finalize WRFV4.X by merging development and bug fixes from release-v4.X branch onto master.
  1. Tag the release on master as an annotated tag
  • git tag -a v4.X

    The tag annotation should be in the below format (optionally, you can add release notes to the annotation):

    WRF Model Version 4.X Release

    This major release of WRF introduces several new options, in
    addition to many improvements and bug fixes for physics schemes,
    dynamics, and miscellaneous features. This release includes
    updates to WRFDA and WRF-Chem, and an updated version of WRF-Hydro.

    See https://github.com/wrf-model/WRF/releases/tag/v4.X for detailed
    release notes.

  1. Carefully inspect git log to make sure the history is as expected. The following example shows that the last release was the v4.2.2 bug fix release:
    commit fb60d61cc44e2a2e8b8311f0b79185724010d510 (tag: v4.2.2, origin/release-v4.2.3)
    Merge: f311cd5e 1e93b7e3
    Author: Ming Chen <__email address__>
    Date: Fri Jan 15 10:21:58 2021 -0700

    Merge remote-tracking branch 'origin/release-v4.2.2'

  2. Push master (which includes the release tag) to wrf-model/WRF. You will need to modify permissions for the master branch on GitHub. To do so, follow these steps: a) go to GitHub.com/wrf-model/WRF
    b) click on settings -> branches -> 'edit' master
    c) remove protections from all checked boxes
    d) save

Then from your local terminal window, issue

  • git push origin master v4.X
  1. Merge master into develop. You will need to modify permissions for the develop branch on GitHub. To do so, follow these steps:
  • go to GitHub.com/wrf-model/WRF
  • click on settings -> branches -> 'edit' develop
  • remove protections from all checked boxes
  • save
  • git checkout develop
  • git merge --no-ff origin/master
  • git push origin develop
  1. Change permissions back to 'protected' for the master and develop branches.
  • go to GitHub.com/wrf-model/WRF
  • click on settings -> branches -> 'edit' develop
  • Click (to turn on) the following boxes:
    • Require pull request reviews before merging
      • Required number of approvals before merging: 2
      • Dismiss stale pull request approvals when new commits are pushed
    • Include administrators
    • Restrict who can push to matching branches
      *** MAKE SURE TO ENTER "wrf-model/merge" in the empty box!
  • save
  • repeat for master branch
  1. Create tar files to attach to the release - for the purpose of those without access to git. Go up a directory and clone the new master branch to include submodules.
  • git clone --recursive-submodules https://github.com/wrf-model/WRF.git WRFVX.X
  • cd WRFVX.X
  • rm -rf .git
  • cd ..
  • tar -cf vX.X.tar WRFVX.X
  • zip vX.X.zip vX.X.tar
  • gzip vX.X.tar
  1. Go to the GitHub release page to finalize the process. https://github.com/wrf-model/WRF/releases.
  • Click "Draft a new release" (top right)
  • Click "Choose a tag" and choose the tag that was just created vX.X
  • For "Release title," enter "WRF Version X.X" or if it's a bug fix release, "WRF Version X.X.X (Bug-fix Release)"
  • Add release notes to the "Describe this release." You may have to make formatting modifications to make it look okay - see previous releases (click edit to see how formatting was done for those).
    • Make sure to include a section at the bottom to tell users which files to download, since GitHub will still create their own files (that will not include NoahMP submodule).
  • Click the box that says "Attach binaries by dropping...." and choose the WRF-X.X.tar and WRF-X.X.tar.gz files. It takes a few minutes to upload both. Note, this will not prevent GitHub from automatically creating its own files, as well. GitHub's files will be called "Source code." No worries - we have a note in the WRF downloads page to instruct users to choose the correct file(s).
  • Use the "Preview" tab to ensure the release notes look okay.
  • Once satisfied, click "Publish release."

After the release is complete, create a new release branch for the next possible release version.

  1. Create the release branch locally from the correct branch.

    Major Release
    The release branch should be branched off of the 'develop' branch and named appropriately (e.g., release-v4.1). Ensure that you are starting from the develop branch and that the develop branch is updated to contain the state of the code intended for release.
  • Locally, create a release branch from the develop branch:
  • git checkout develop
  • git checkout -b release-v4.X

    Minor Release
    The release branch should be branched off of the most recent (or relevant) 'master' branch (which should only contain released/tagged code), and named appropriately (e.g., release-v4.0.1). Ensure that the last update to the master branch was the previous (or relevant) release.
  • Locally, create a release branch from the master branch:
  • git checkout master
  • ensure that the state of the code is from that of the intended tag (e.g., the new release you just created)
  • git checkout -b release-v4.0.X
  1. Push the release branch to origin.
  • git push origin release-v4.X

There is no need to create a PR for the newly-created branch. Once the branch has been pushed to 'origin,' it should be ready to use. Once the release branch is created, the only modifications should be bug fixes. Core maintainers can merge approved pull requests to the release branch while the branch is still active.

Clone this wiki locally