Skip to content

Creating a WRF Code Release

Jump to bottom
Kelly Werner edited this page May 11, 2021 · 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.
  • See the annotation of the v4.X tag for full release notes (git show v4.X).
  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. Draft and save the release description at: https://github.com/wrf-model/WRF/releases.

  2. 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
    • 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

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