Release Process#
This document elaborates on the process defined by release.toml in the kube workspace.
Versioning#
We release all public workspace crates with the same version.
The crates are published in reverse order of inclusion, releasing the final facade crate kube
last, so users do not notice any version-mismatches during releases.
You should only need to depend on kube
Only kube = {...}
needs an entry in your Cargo.toml
, as kube
re-exports the sub-crates.
Cadence#
We have no fixed release cadence, but we still try to release roughly once a month, or whenever important PRs are merged (whichever is earliest).
For maintainers: Cutting Releases#
Cutting releases is a task for the maintenance team (contributing) and requires developer tools installed.
The process is mostly automated once the preliminary steps are taken, and a publish should complete in 5m with everything setup.
You have the option to write highlights in the release notes, but this can be elided with a "Publish" button press on the draft release.
Preliminary Steps#
Close the current ongoing milestone, and create the next one. Move over any unmerged PRs to the next milestone.
Release Notes Depend on Github Release Notes Labels
For best success, every PR should have one changelog-*
label and should be included in the current milestone (to avoid scouring prs merged since the last version later).
Ensure the PRs in the milestone all have exactly one changelog-*
label to ensure the release notes are generated correctly (we follow Keep a Changelog with the setup as outlined in #754).
Publishing Crates#
Start the process on latest main
by publishing to crates.io with cargo-release
locally using the latest stable rust toolchain installed, and git setup to be able to sign tags. Run:
PUBLISH_GRACE_SLEEP=20 cargo release minor --execute
once this completes, the following crates should all have been published to crates.io:
The crate publish will enqueue a documentation build in docs.rs.
docs.rs failures
If the docs.rs
build fails, please create an issue for it with the build log from docs.rs.
As part of the cargo release
, a signed git tag will automatically be pushed to kube/tags.
Publishing the Release#
Once crates have been published and the corresponding tag pushed, a GitHub Release will be generated by the release job in the draft state. This can be edited for extra documentation / migration notes. The section below contains ideas for what to include.
Publish Soon
We should not spend too much time adding extra information (<1h), because dependabot will quickly pick up on a release, and start publishing dependency update PRs to downstream users. If our release notes are not ready, they might see a PR without release notes.
Adding Documentation#
If you are writing extra documentation, then start editing the draft release.
You will notice auto-generated notes already present in the textarea
along with new contributors - please leave these lines intact!
Check if any of the PRs in the release contain any notices or are particularly noteworthy.
We advocate for highlighting some or more of the following, as part of the manually written header:
- big features
- big fixes
- contributor recognition
- interface changes
See the appendix below for ideas.
Symbol links from the Release
If the enqueued documentation build in docs.rs done, then it is possible to link to them in the release.
docs.rs build time
The docs.rs build usually completes in less than 30m
after publishing, but we have seen it take around half a day when publishing during an anticipated Rust release.
A release is more than just a
git tag
, it should be something to celebrate, for the maintainers, the contributors, and the community.
Of course, not every release is going to be noteworthy.
For these cases, it's perfectly OK to just hit Publish without much ceremony.
Completion Steps#
- Press Publish on the GitHub Release
- Run
./scripts/release-afterdoc.sh NEW_VERSION
to port the changed release notes into theCHANGELOG.md
and push tomain
- Run
./sync.sh
in the website repo to pull the new release notes to kube.rs/changelog
Appendix#
Header Formatting Tips#
Some example release notes from recent history has some ideas:
Note that headers should link to PRs/important documents, but it is not necessary to link into the release or the milestone in this document yourself (the afterdoc
step automates this).
For breaking changes; consider including migration code samples for users if it provides an easier way to understand the changes. Fenced code blocks with diff
language are easy to scan:
-async fn reconcile(myobj: MyK, ctx: Arc<Data>) -> Result<ReconcilerAction>
+async fn reconcile(myobj: Arc<MyK>, ctx: Arc<Data>) -> Result<ReconcilerAction>
New features should link to the new additions under docs.rs/kube once the documentation build completes.
...