Skip to content

Creating a WRF Code Release

Jump to bottom
Kelly Werner edited this page Apr 20, 2023 · 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.

NOTE: You must have your SSH key set up on GitHub to be able to proceed.

Creating the release

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

STEP 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:

  • Go to GitHub.com/wrf-model/WRF
  • Click on settings -> branches -> 'edit' release-v4*
  • Uncheck the box beside "Require a pull request before merging." Nothing else needs to be unchecked.
  • Save
  • Double-check your modified files, and then you can approve and squash/merge your modifications.
  • Go back to GitHub.com/wrf-model/WRF and re-set the release branch permissions.
    • Check - Require a pull request before merging.
    • Check - Require approvals and set Required number of approvals before merging: 2
    • Check - Dismiss stale pull request approvals when new commits are pushed
    • Save

STEP 2
Go back to your terminal window and clone the main wrf-model/WRF repository as a new directory and then move into that directory.

  • git clone --recurse-submodule https://github.com/wrf-model/WRF.git WRF_RELEASE_PREP
  • cd WRF_RELEASE_PREP

STEP 3
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)


STEP 4
Locally merge the release branch into master.

  • git checkout master
  • git merge --no-ff origin/release-v4.X

    You should then have the option to add a comment, but the default is fine:

Merge remote-tracking branch 'origin/release-vX.x.x


STEP 5
Tag the release on master as an annotated tag.

  • git tag -a v4.X

    The tag annotation should be in the below format.

WRF Model Version 4.X Release


STEP 6
Check the 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:

  • git log


Merge remote-tracking branch 'origin/release-vX.x.x'


STEP 7
Push master (which includes the release tag) to wrf-model/WRF. You must modify permissions for the master branch on the GitHub website. To do so, follow the instructions in step 1 for editing the master branch. Then from your local terminal window, issue

  • git push origin master v4.X

**Afterward, MAKE SURE TO RESET THE PERMISSIONS, AS IS DESCRIBED IN step 1**

STEP 8
Merge master into develop. You will need to modify permissions for the develop branch on GitHub. To do so, again follow the instructions in step 1 for editing the develop branch. Then from your local terminal window, issue

  • git checkout develop
  • git merge --no-ff origin/master
  • git push origin develop

**Afterward, MAKE SURE TO RESET THE PERMISSIONS, AS IS DESCRIBED IN step 1**

STEP 9
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.

  • cd ..
  • git clone --recurse-submodule 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

STEP 10
Go to the GitHub release page to finalize the process.

  • 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 may be necessary to upload these one at a time). It takes a few minutes to upload both. It may say the file size is too large, but it will upload it anyway, so this can be ignored. 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.


STEP 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).

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

  • 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

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

Non-GitHub Updates

  • Compile new code on Cheyenne.
  • Send a message to wrf-news about release.
  • Post a message on forum in Announcement section.
Clone this wiki locally