Unified Workflow Tools Release Procedure

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. If the newly created branch is correct for release as-is, skip to step 4. Otherwise, target it with a PR from a fork and perform any of the following tasks that are appropriate:
   1. Update the version of build number, follow the Update the version or build number procedure, below.
   2. Apply any required updates (e.g. bug fixes). This might include cherry picking or otherwise selectively applying diffs from other branches.
   3. For updates to old releases, consider whether CI logic 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 require updates.
   4. As a meta-procedure, consider whether similar bug fixes etc. 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. For major- or minor-version updates, the previous release is the latest minor release. For patch-version updates, the previous release is the latest patch release.
   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. Click + Add version, enter the new release's <major>.<minor>.<patch> branch name in the search box, click the branch name (not the v-prefixed tag) when it appears, enable Active and disable Hidden, then click Update version.
2. From the main Versions page, if any v-prefixed tags appear in the list, click its ... menu, select Configure version, disable Active, enable Hidden, then click Update version.

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.