Skip to content

Creating a WRF Code Release

Jump to bottom
Kelly Werner edited this page Mar 29, 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

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.1
  1. Tag the release on master as an annotated tag

  • git tag -a v4.1
    The tag annotation should be in the below format (optionally, you can add release notes to the annotation):

    Finalize WRFV4.1 by merging bug fixes from release-v4.1 branch onto master.
    See the annotation of the v4.1 tag for full release notes (git show v4.1).

  1. Carefully inspect git log to make sure the history is as expected. The following example shows that the last release was the v4.0.1 bug fix release:
    commit f729619f0dac9312d4853b8cc56817c75ad49eba (HEAD -> master, tag: v4.0.1, upstream/release-v4.0.2, upstream/master, release-v4.0.2)
    Merge: a41f34e4 07f50a40
    Author: Kelly Werner <kkeene@ucar.edu>
    Date: Tue Oct 2 16:17:21 2018 -0600

    Merge pull request #651 from wrf-model/release-v4.0.1

    Finalize WRFV4.0.1 by merging bug fixes from release-v4.0.1 branch onto master. See the annotation of the v4.0.1 tag for full release notes (git show v4.0.1).

  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

  • git push origin master v4.1
  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
    • 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.1

    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.1
  1. Push the release branch to origin.
  • git push origin release-v4.0.1

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