Skip to content

Unified Workflow Tools Release Procedure

Jump to bottom
Paul Madden edited this page Jan 7, 2025 · 5 revisions

For software releases, which may include documentation updates:

  1. Create a release branch named for the new <major>.<minor>.<patch> version (e.g. 2.1.0) in the ufs-community/uwtools repository. Create the branch directly from main for major- or minor-version releases, or from a previous release branch for bug-fix releases (e.g. bug-fix release branch 2.1.1 created from previous release branch 2.1.0). This step must be performed by a repo admin, as creation of new branches is restricted.
  2. Target the new release branch with a PR from a fork.
    1. Follow the Update the version or build number procedure, below, as required for the release.
    2. Add any other necessary updates (e.g. bug fixes) to the PR, including changes cherry picked or otherwise selectively applied from other branches.
    3. For updates to old releases, consider whether anything under .github needs to be updated. This should be uncommon: If the package built in CI previously it should do so again. But certain changes to the repository configuration (e.g. names of repository secrets used in CI workflows) might necessitate changes under .github.
    4. As a meta-procedure, consider whether similar changes should be applied to other releases. For example, it may be appropriate to accompany a 2.1.0 -> 2.1.1 bug-fix release with a 2.2.0 -> 2.2.1 release fixing the same bug for the 2.2.x series.)
  3. Merge the PR to the new release branch.
  4. Run the Release CI workflow against the new release branch via the GitHub web interface:
    1. On the Actions page, click Release under All workflows in the left pane.
    2. Click the Run workflow pull-down, select the new release branch, then click the green Run workflow button.
    3. Wait for the workflow to complete, then confirm publication of the new package on anaconda.org.
  5. Create a GitHub release for the new version via the GitHub web interface:
    1. Click Releases, then Draft a new release.
    2. Set Target to the new release branch.
    3. Click Choose a tag, then enter the version number with a "v" prefix, e.g. v2.1.0 for version 2.1.0. This ensures that the tag name is distinct from the release branch name. Click + below the text-entry field to create the new tag when the release is published.
    4. Set the Previous tag appropriately.
    5. Enter the Release title to match the tag (e.g. v2.1.0).
    6. Click Generate release notes to pre-populate the release-description text box.
    7. Edit the pre-populated notes.
      1. Edit the What's Changed section to provide a synopsis of the release's high points. Use the list of PRs/commits as a guide, but summarize.
      2. Remove the New Contributors section, if present.
      3. Retain the Full Changelog section as generated.
    8. Ensure that Set as the latest release is selected if this is the very latest uwtools version (vs, say, a bug-fix release for an older version).
    9. Click the green Publish release button.
  6. On main, follow the Update the version or build number, below, to set the version number for the next expected major.minor.0 release.

Read the Docs will build and publish documentation for the new release due to having been notified about it by a webhook on the GitHub repository. As an RtD admin, visit the versions page and

  1. Edit any <major>.<minor>.<patch> versions (corresponding to git branches, which may receive future documentation updates) for which documentation should be displayed in the RtD fly-out menu to enable Active and disable Hidden.
  2. Edit any v<major>.<minor>.<patch> versions (corresponding to git tags, which should be static over time) to disable Active and enable Hidden.

For documentation-only updates to existing releases:

  • Target the appropriate release branch with a PR updating content under docs/.
  • The src/ directories must not change, and recipe/ should only change in conjunction with a build update (see procedure immediately below).
  • Merge the PR.
  • Read the Docs will be notified of commits to monitored branches and will rebuild and publish the updated docs under the existing version.
  • Update the out-of-date tag (see procedure below).

For build updates to existing releases:

  • Target the appropriate release branch with a PR updating buildnum in src/uwtools/resources/info.json and/or content in recipe/meta.yaml (e.g. pins on dependency packages). The version number must not change.
  • The docs/ directory should only change in conjunction with a documentation-only update (see procedure immediately above).
  • In general, code under src/ should not change, though test updates may sometimes be appropriate.
  • After making the needed updates, in a base conda environment with the condev package installed (i.e. not in a development shell), run make meta, which will update recipe/meta.json based on the updated info.json and meta.yaml.
  • Merge the PR.
  • Execute (only) the "Run the Release CI workflow" step from the main release procedure. Do not proceed to the GitHub release step.
  • Update the out-of-date tag (see procedure below).

Update an out-of-date tag after a documentation-only or build update

In a fresh or up-to-date clone of the main repo (not a fork):

  • Check out the branch: git checkout <major>.<minor>.<patch>.
  • Confirm that the v<major>.<minor>.<patch> tag points to a non-HEAD commit in the output of git log.
  • Update the tag locally: git tag v<major>.<minor>.<patch> --force.
  • Confirm that the v<major>.<minor>.<patch> tag now points to the HEAD commit in the output of git log.
  • Push the tag: git push origin tag v<major>.<minor>.<patch> --force.

Update the version or build number

Update the info.json resource file, setting version to the required version and buildnum to 0. Then, in a base conda environment with the condev package installed (i.e. not in a development shell), run make meta, which will update recipe/meta.json based on the updated recipe/meta.yaml and info.json.

Clone this wiki locally