RELEASES.md
This document describes the current release and versioning strategy. This strategy is likely to change as Rerun matures.
:warning: The steps & workflows in this document are targeting the open-source Rerun repository (https://github.com/rerun-io/rerun), not our internal monorepo.
New Rerun versions are released every two weeks. Sometimes we do out-of-schedule patch releases. We do not block a release on a PR. Incomplete work should be hidden behind a feature flag.
Each release include new versions of:
We use semantic versioning. All versions are increased in lockstep, with a minor version bump each time (0.1.0, 0.2.0, 0.3.0, …).
This means we might add breaking changes in each new release.
In rare cases we will do patch releases, e.g. 0.3.1, when there is a critical bug fix. These patch releases will not contain any breaking changes.
We sometimes do pre-releases. Then we use the versioning 0.2.0-alpha.0 etc.
The version on our main branch is always an -alpha.N+dev version. We build artifacts from main every day, though these are not published on package registries.
You can find the latest development version in our GitHub releases.
Our Minimum Supported Rust Version (MSRV) is always at least one minor release behind the latest Rust version, and ideally two releases.
We have not yet committed to any backwards or forwards compatibility.
We tag all data files (.rrd files) and communication protocols with the Rerun version number. If there is a version mismatch, a warning is logged, but an attempt is still made to load the older or newer data.
As of 0.23, we automatically migrate data from older versions, with an N-1 compatibility policy. That means 0.24 supports migrating 0.23 data, 0.25 supports migrating 0.24 data, etc.
Before doing anything, read all the steps in full!
There usually isn't any ambiguity, as releases are planned ahead of time.
You can always find the latest release on our GitHub releases page.
The branch name is the single source of truth for the release version. Our release workflow automatically updates all versions in the repository to what is specified in the branch name, so the format is important:
prepare-release-0.x.y for minor and patch releases.prepare-release-0.x.y-alpha.N for alpha releases.Note that prepare-release-0.x is invalid. Always specify the y, even if it is 0, e.g. prepare-release-0.15.0 instead of prepare-release-0.15.
The base of the branch should depends on what kind of release it is:
main.docs-latest ( :warning: branching off docs-latest instead of the latest release tag ensures that documentation patches will be included)main.You can do this either using git on your command line, or through the UI:
Once the branch has been created, push it to the remote repository.
NOTE (for patch releases): upon creation of the branch, the version is set to the final version of the previous release. This can create issues when testing the patch release, since it has a non-"+dev" version identical to/conflicting with an existing release. Because of that, an RC (release candidate) should preferably be created before testing. The release workflow section below explains how you can create an RC. Do this once you have prepared your patch-release branch and it's ready for testing.
In GitHub we have a consider-patch label that we put on PRs that we might want to include in the release.
The fastest way to get an overview of all the patch candidate PRs from both repositories and their corresponding commit hashes is to run this script:
uv run scripts/fetch_patch_candidates.py
After cherry-picking a commit into the patch, please make sure to remove the consider-patch label.
CHANGELOG.md⚠️ Skip this step when preparing an alpha release.
The curated part of the release notes — highlights, breaking changes & migration guides, and new
features, including any screenshots/GIFs — is written incrementally during the cycle, per PR:
every include in changelog PR drops one file in docs/content/changelog/upcoming/
(one file per PR avoids merge conflicts).
At release, assemble those entries into the release's changeset:
This whole step is an agent-friendly task — run the /assemble-changelog skill (Claude Code), which
does it end to end:
upcoming/*.md into docs/content/changelog/changeset-0-xx.md, grouping each entry by
its type: hint (highlight / breaking / feature), merging and de-duplicating the entries.TODO(name) placeholders.CHANGELOG.md,
via pixi run uvpy scripts/generate_changelog.py --version 0.x.y — edit PR titles/labels to
improve the output.redirect: in docs/content/changelog.md at this
release's changeset (scripts/ci/check_changelog_redirect.py requires the newest changeset to be
the redirect target, so this must land together with the new changeset).upcoming/ (leaving _template.md).Then review the result:
TODO(name) in the changeset (docs links, example links, screenshots/GIFs, migration guides).
The release is blocked until all of these are resolved.## Highlights section reads well as a whole. (Feature leads write their own items per PR;
here you just make sure the one-line and multi-line summary of the release hang together.)The changeset is not copied into CHANGELOG.md. The script summarizes it instead — the section
headings plus links to the changeset on the website — so the full prose lives in exactly one place.
Do not create the next release's changeset yet: an empty changeset for an unreleased version would
fail the redirect check in CI. The next changeset is created from
docs/content/changelog/_template.md when that release is
assembled. Until then the now-empty upcoming/ folder collects
the next release's per-PR entries.
⚠️ Skip this step when preparing an alpha release.
Remove all the #[docs(unreleased)] attributes in re_type_definitions, followed by pixi run codegen.
Remove the speculative link markers (?speculative-link).
Update the python support table for the major release.
Once you're done, commit and push onto the release branch.
In the UI:
Use workflow from to the release branch you created in step (2).alpha if the branch name is prepare-release-x.y.z-alpha.N.
This will create a one-off alpha release.
rc if the branch name is prepare-release-x.y.z.
This will publish a release candidate.
final for the final public release.
In all three cases, the workflow opens (or updates) a release pull request against main.
Once the release workflow is started, it will create a pull request for the release. The pull request description will tell you what to do next.
The Release workflow will build artifacts, run PR checks, and publish them to PyPI, crates.io, npm, etc.
For rc and final releases it also creates a draft GitHub release (in the tag-release job) and attaches a comment to the release PR pointing at it.
Once the Release workflow has finished successfully and you've sanity-checked the artifacts, verify that the GitHub release draft contains the summary from CHANGELOG.md, not the full website changeset, then click Publish release.
Publishing the release triggers the GitHub Release workflow, which syncs the binary assets from build.rerun.io onto the published GitHub release.
Make sure that workflow also finishes successfully so the release ends up with all of its assets attached.
mainThe release branch will contain a post-release version bump commit made by the release bot.
For example, prepare-release-0.25.0 will be bumped to 0.26.0-alpha.1+dev once everything has been released.
Additionally, it's common for us to push small changes and bug fixes directly to the release branch.
We want all of this to land back on main, so:
main.main and cherry-pick the commits. This includes at least
the CHANGELOG.md update, plus any other changes made on the release branch that haven't been cherry-picked in the
first place.main.Make sure the consider-patch label on GitHub is up-to-date. For a full release, this usually means removing it from all PRs.
Summarize your experience with the release process to our Release Postmortems Notion page.
Create tickets if you think we can improve the process, put them into the Actionable items section.
uv run scripts/fetch_patch_candidates.py will show a warning for consider-patch-labeled PRs that have been merged before a release.
Make sure to remove the label from PRs that are already part of a release.