Release Checklist#
With every release of xNVMe, the following tasks must be ticked off.
Initially, the window of features are closed, that is, all PRs intended for the
release are integrated on main and all tests are passing.
A release is made by merging a pull-request whose last commit is the
version bump, ver: bump to vX.Y.Z. The publish-release workflow then
tags main and creates the release from the artifacts the pull-request’s
own verify run produced, and starts the run that builds and deploys the
documentation of the tag, as publish-docs does for main; see
When the jobs run, and what is published. So the order of the commits matters, and the bump is
committed last, after the files generated by the bumped version:
Bump the version-number in the working tree, without committing it
Run
make version VERSION=X.Y.Z, which sets it inmeson.build,python/bindings/setup.py,rust/xnvme-sys/Cargo.toml(twice) andcijoe/pyproject.toml, or in none of them when one no longer matchespython3 toolbox/xnvme_release.py "ver: bump to vX.Y.Z"checks them, once theCHANGELOG.rstsection exists
Update man-pages
Build and install the version-bumped xNVMe
Then run:
make gen-man-pagesCommit the man-pages with message:
docs(man): update for vX.Y.ZThe Bash completion,
toolbox/bash_completion.d/xnvme, asksxnvmewhat to complete, so it needs no update
Update
CONTRIBUTORS.mdmake contributorsprints the authors since the previous tag thatCONTRIBUTORS.mddoes not name;git log <previous-tag>..HEAD --format="%aN <%aE>"gives their addressesUpdate the lists accordingly, until
make contributorsprints nothingCommit changes with the message:
CONTRIBUTORS: update for vX.Y.Z
Update
CHANGELOG.rst, as the commit before the bumpGo over the changes and summarized the different scopes, in a section named
vX.Y.Z; it becomes the notes of the releaseCommit changes with the message:
CHANGELOG: update for vX.Y.Z
Commit the version bump last, with the message
ver: bump to vX.Y.ZOpen a pull-request for the release-prep commits
The release-prep commits (man-pages, CONTRIBUTORS, CHANGELOG, version bump) go through PR review like any other change
source-format-checkfails the pull-request when its last commit is a bump that does not match the version files or has noCHANGELOG.rstsectionRun every gated job, as the release should carry their results, by adding the label
gate:all, then re-running thegatesjob of the latest run, as adding a label starts noneKeep the pull-request up to date with
main, as branch protection requires; a release is only made from a run that tested the tree that landsGet review and wait for tests to finalize / pass
Merge onto
main, as a rebase
Check the release
The
publish-releaseworkflow tagsmainasvX.Y.Zand creates the release on GitHUB, titledRelease Notes: vX.Y.Z, with theCHANGELOG.rstsection followed by the generated release notesIts assets are the source archives
xnvme-X.Y.Z.tar.gz(without subprojects) andxnvme-fat-X.Y.Z.tar.gz(including SPDK sources), with their.sha256sum, the Python sdistxnvme-py-sdist-vX.Y.Z.tar.gz, and the test results of the pull-request’s run intest-results-vX.Y.Z.tar.gzDouble-check the generated docs at https://xnvme.io/ and https://xnvme.io/en/vX.Y.Z. They are built by
docgenruns ofverifyapart from the release, onmainand on the tag, so a release can exist while its documentation failed; then re-run the failed run, or startverifyon the tag withjobset todocgenWhen the
publish-releaserun failed or was cancelled, re-run it from the Actions tab; it releases from the same commit and artifacts. Do not tag by hand
Publish the Python package
We wish to publish the Python package that have been utilized for testing and provided as artifact for the release. Thus, download and rename it, then upload it.
Rename:
xnvme-py-sdist-vX.Y.Z.tar.gz xnvme-X.Y.Z.tar.gzUpload:
twine upload xnvme-X.Y.Z.tar.gz
Publish the Rust crate
Create an API token on https://crates.io
Set up credentials locally
cargo loginUpload:
cd rust/xnvme-sys && cargo publish