The release process for all the crates in kube is briefly outlined in release.toml.
We currently release all crates with the same version.
The crates are thus version-locked and new version in certain sub-crates does not necessarily guarantee changes to that crate.
Our changelog considers changes to the facade crate
kube as the highest importance.
The crates are published in reverse order of importance, releasing the final facade crate
kube last, so users who depend on this do not notice any version-mismatches during releases.
We currently have no fixed cadence, but we still try to release roughly once a month, or whenever important PRs are merged (whichever is earliest).
For maintainers: Cutting Releases#
The process is automated where possible, and the non-writing bits usually only take a few minutes, whereas the management of documentation and release resources require a bit of manual oversight.
Start the process by publishing to crates.io (crate-by-crate) locally with the latest stable rust toolchain installed and active:
PUBLISH_GRACE_SLEEP=20 cargo release minor --execute
once this completes, double check that all the crates are correctly published to crates.io:
This will enqueue a documentation build in docs.rs to complete.
Docs build usually completes in less than
30m, but we have seen it take around half a day when publishing during an anticipated rust release.
Generating the release#
Once the crates have been published, we can start the process for creating a GitHub Release.
If you just published, you will have at least one commit unpushed locally. You can push and tag this in one go using it:
However, we should not publish this until the enqueued documentation build in docs.rs completes.
We use this wait-time to fully prepare the release, and write the manual release header:
Editing the draft#
At this point we can edit the draft release. Click the edit release pencil icon, and start editing.
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 strongly advocate for highlighting some or more of the following, as part of the manually written header:
- big features
- big fixes
- contributor recognition
- interface changes
A release is more than just a
git tag, it should be something to celebrate, for the maintainers, the contributors, and the community.
See the appendix below for ideas.
Of course, not every release is going to be noteworthy.
For these cases, it's perfectly OK to just hit Publish without much ceremony.
- Create a new milestone for current minor version + 1
- Press Publish on the release once docs.rs build completes
./scripts/release-afterdoc.shto port the changed release notes into the
./sync.shin the website repo to port the new release notes onto the website
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.