How to Prepare a Release
In this guide, we’ll cover:
Preparing the Documentation
Bumping the Version
Releasing On GitHub
Releasing The Software On Anaconda
Creating a New Version of the Documentation
Preparing the Documentation
This step is only required for production releases, not release candidates.
Checkout a branch
git fetch upstream main git checkout -b versioned-docs upstream/main
Edit
docs/source/parameters.rst
: inhttps://github.com/E3SM-Project/zppy/blob/main/zppy/templates/default.ini
, replacemain
with the hash of the latest commit.Create a pull request to the main repo and merge it. Now, when the next version of the documentation is created (see last part of this page), it will point to the relevant defaults. Mark yourself as the assignee, and mark “Documentation” as the label.
Bumping the Version
Checkout a branch with the name of the version.
git fetch upstream main # Prepend "v" to <version> # For release candidates, append "rc" to <version> git checkout -b v<version> upstream/main
Bump version using tbump. Example, bumping to v1.1.0:
# Exclude "v" and <version> should match the above step. # --no-tag is required since tagging is handled in "Releasing on GitHub" $ tbump <version> --no-tag :: Bumping from 1.0.0 to 1.1.0 => Would patch these files - setup.py:26 version="1.0.0", + setup.py:26 version="1.1.0", - zppy/__init__.py:1 __version__ = "v1.0.0" + zppy/__init__.py:1 __version__ = "v1.1.0" - conda/meta.yaml:2 {% set version = "1.0.0" %} + conda/meta.yaml:2 {% set version = "1.1.0" %} - tbump.toml:5 current = "1.0.0" + tbump.toml:5 current = "1.1.0" => Would run these git commands $ git add --update $ git commit --message Bump to 1.1.0 $ git push origin v1.1.0 :: Looking good? (y/N) >
If you encounter
Error: Command `git push upstream main` failed
, as in issue 470, you can rungit push upstream main
yourself.Create a pull request to the main repo and merge it. Mark yourself as the assignee, and mark “Update version” as the label.
Releasing on GitHub: release candidates
Create a tag for the release candidate at https://github.com/E3SM-Project/zppy/tags. Example, bumping to v1.1.0rc1:
$ git checkout main $ git fetch upstream $ git reset --hard upstream/main $ git tag -a v1.1.0rc1 -m "v1.1.0rc1" # Delete the branch from the tbump step. Otherwise, the push command won't work. $ git branch -D v1.1.0rc1 $ git push upstream v1.1.0rc1
Releasing on GitHub: production releases
Draft a new release here. You can save this and come back to it later, if need be.
Set Tag version to
v<version>
, including the “v”. @Target should bemain
.Set Release title to
v<version>
, including the “v”.Use Describe this release to summarize the changelog.
You can scroll through zppy commits for a list of changes.
You can look at the last release to get an idea of how to format the description.
Click Publish release.
CI/CD release workflow is automatically triggered.
Releasing on conda-forge: release candidates
If you don’t have a local version of the conda-forge repo, run:
git clone git@github.com:conda-forge/zppy-feedstock.git git remote add upstream git@github.com:conda-forge/zppy-feedstock.git
If you don’t have a fork of the conda-forge repo, on conda-forge, click the “Fork” button in the upper right hand corner. Then, on your fork, click the green “Code” button, and copy the SSH path. Run:
git remote add <your fork name> <SSH path for your fork>
Get the sha256 of the tag you made in “Releasing on GitHub: release candidates”:
curl -sL https://github.com/E3SM-Project/zppy/archive/v1.1.0rc1.tar.gz | openssl sha256
Make changes on a local branch. Example, bumping to v1.1.0rc1:
$ git fetch upstream dev $ git checkout -b v1.1.0rc1 upstream/dev # You can name the branch anything you want # In `recipe/meta.yaml`, update the version and sha256 (and the build number if needed): {% set version = "1.1.0rc1" %} # Set to your version sha256: ... # The sha256 from the previous step number: 0 # build > number should always be 0 $ git add -A $ git commit -m "v1.1.0rc1" $ git push <your fork name> v1.1.0rc1
Note that the conda-forge bot does not work for release candidates. So, make a PR manually from your fork of the feedstock to the
dev
branch of conda-forge. Then, the package build on conda-forge will end up with thezppy_dev
label. You can add the “automerge” label to have the PR automatically merge once CI checks pass.After merging, CI runs again (in a slightly different way). Then, check the https://anaconda.org/conda-forge/zppy page to view the newly updated package. Release candidates are assigned the
zppy_dev
label. Note that it takes about 15 minutes for the files to propagate across conda-forge’s mirroring services, which must happen before you can use the files.
Releasing on conda-forge: production releases
Be sure to have already completed Releasing On GitHub. This triggers the CI/CD workflow that handles Anaconda releases.
Wait for a bot PR to come up automatically on conda-forge after the GitHub release. This can happen anywhere from 1 hour to 1 day later.
Re-render the PR (see docs).
Merge the PR on conda-forge.
Check the https://anaconda.org/conda-forge/zppy page to view the newly updated package. Production releases are assigned the
main
label.Notify the maintainers of the unified E3SM environment about the new release on the E3SM Confluence site.
Be sure to only update the
zppy
version number in the correct version(s) of the E3SM Unified environment.This is almost certainly one of the E3SM Unified versions listed under “Next versions”. If you are uncertain of which to update, leave a comment on the page asking.
Creating a New Version of the Documentation
Be sure to have already completed Releasing On GitHub. This triggers the CI/CD workflow that handles publishing documentation versions.
Wait until the CI/CD build is successful. You can view all workflows at All Workflows.
Changes will be available on the zppy documentation page. You can check if it really is the latest version, by going to https://e3sm-project.github.io/zppy/_build/html/main/parameters.html, then checking if the “paramter defaults” link includes the proper hash. It should match the commit before “Update defaults in docs” on https://github.com/E3SM-Project/zppy/commits/main.
Extra Resources
Conda-forge: