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 in meson.build, python/bindings/setup.py, rust/xnvme-sys/Cargo.toml (twice) and cijoe/pyproject.toml, or in none of them when one no longer matches

    • python3 toolbox/xnvme_release.py "ver: bump to vX.Y.Z" checks them, once the CHANGELOG.rst section exists

  • Update man-pages

    • Build and install the version-bumped xNVMe

    • Then run: make gen-man-pages

    • Commit the man-pages with message: docs(man): update for vX.Y.Z

    • The Bash completion, toolbox/bash_completion.d/xnvme, asks xnvme what to complete, so it needs no update

  • Update CONTRIBUTORS.md

    • make contributors prints the authors since the previous tag that CONTRIBUTORS.md does not name; git log <previous-tag>..HEAD --format="%aN <%aE>" gives their addresses

    • Update the lists accordingly, until make contributors prints nothing

    • Commit changes with the message: CONTRIBUTORS: update for vX.Y.Z

  • Update CHANGELOG.rst, as the commit before the bump

    • Go over the changes and summarized the different scopes, in a section named vX.Y.Z; it becomes the notes of the release

    • Commit changes with the message: CHANGELOG: update for vX.Y.Z

  • Commit the version bump last, with the message ver: bump to vX.Y.Z

  • Open 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-check fails the pull-request when its last commit is a bump that does not match the version files or has no CHANGELOG.rst section

    • Run every gated job, as the release should carry their results, by adding the label gate:all, then re-running the gates job of the latest run, as adding a label starts none

    • Keep 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 lands

    • Get review and wait for tests to finalize / pass

    • Merge onto main, as a rebase

  • Check the release

    • The publish-release workflow tags main as vX.Y.Z and creates the release on GitHUB, titled Release Notes: vX.Y.Z, with the CHANGELOG.rst section followed by the generated release notes

    • Its assets are the source archives xnvme-X.Y.Z.tar.gz (without subprojects) and xnvme-fat-X.Y.Z.tar.gz (including SPDK sources), with their .sha256sum, the Python sdist xnvme-py-sdist-vX.Y.Z.tar.gz, and the test results of the pull-request’s run in test-results-vX.Y.Z.tar.gz

    • Double-check the generated docs at https://xnvme.io/ and https://xnvme.io/en/vX.Y.Z. They are built by docgen runs of verify apart from the release, on main and on the tag, so a release can exist while its documentation failed; then re-run the failed run, or start verify on the tag with job set to docgen

    • When the publish-release run 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.gz

    • Upload: 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 login

    • Upload: cd rust/xnvme-sys && cargo publish