diff --git a/RELEASES.md b/RELEASES.md index a44b10ec504b..228e920c9b00 100644 --- a/RELEASES.md +++ b/RELEASES.md @@ -31,6 +31,9 @@ In rare cases we will do patch releases, e.g. `0.3.1`, when there is a critical 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](https://github.com/rerun-io/rerun/releases/tag/prerelease). + ## Rust version policy Our Minimum Supported Rust Version (MSRV) is always _at least_ one minor release behind the latest Rust version, and ideally two releases. @@ -43,54 +46,39 @@ Our Minimum Supported Rust Version (MSRV) is always _at least_ one minor release 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. -## Releases - -Release builds of the Python Wheels are triggered by pushing a release tag to GitHub in the form `0.2.0`. -If we are doing a patch release, we do a branch off of the latest release tag (e.g. `0.3.0`) and cherry-pick any fixes we want into that branch. - -## Alpha vs final releases - -The overall process slightly differs between alphas and final releases. - -For alpha releases, the process is essentially fully-automated and throw-away. Specifically: +# Release process -- We do not update `CHANGELOG.md` (though we may have a raw changelog in the GH release) -- When failing, it's fine to just start over with a new alpha. -- The release branch typically has no content other than the automatically generated version bump. -- The release branch doesn't need to be merged to `main` (and shouldn't, unless the workflow fully succeeds). +Before doing anything, read all the steps in full! -For final releases with a minor or minor version bump, the process is typically more involved: +### 1. Determine what the next version should be. -- At least `CHANGELOG.md` must be updated on the branch. -- Typically more commits are pushed or cherry-picked for last-minute fixes. -- One or more RCs are triggered before the final release. -- The release branch _must_ be merged to `main`. +There usually isn't any ambiguity, as releases are planned ahead of time. -The same applies for final releases with a patch version bump, except the branch starts from the previous major/minor release instead of `main`. Also, special care is required with `docs-latest` (see below). +You can always find the latest release on our [GitHub releases](https://github.com/rerun-io/rerun/releases/tag/prerelease) page. -# Release process +### 2. Create a release branch. -### 1. Check the root [`Cargo.toml`](./Cargo.toml) to see what version we are currently on. +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: -### 2. Create a release branch. +- `prepare-release-0.x.y` for minor and patch releases. +- `prepare-release-0.x.y-alpha.N` for alpha releases. -The name should be: +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`. -- `release-0.x.y` for final releases and their release candidates. -- `release-0.x.y-alpha.N` where `N` is incremented from the previous alpha, - or defaulted to `1` if no previous alpha exists. - **IMPORTANT**: because alpha releases branches are not always merged, the version on `main` (e.g. in `Cargo.toml`, etc.) may not match the last alpha release. So always double-check the actual version of the last alpha release by visiting our [PiPy](https://pypi.org/project/rerun-sdk/#history) page. +The _base_ of the branch should depends on what kind of release it is: -Note that `release-0.x` is _invalid_. Always specify the `y`, even if it is `0`, -e.g. `release-0.15.0` instead of `release-0.15`. +- For a _minor_ release, the branch is created from `main`. +- For a _patch_ release, the branch is created from the previous release tag. +- For an _alpha_ release, the branch is created from `main`. -For minor release, the branch is typically created from `main`. For patch release, the branch is typically created -from the previous release's tag. +You can do this either using `git` on your command line, or through the UI: ![Image showing the branch create UI. You can find the `new branch` button at https://github.com/rerun-io/rerun/branches](https://github.com/rerun-io/rerun/assets/1665677/becaad03-9262-4476-b811-c23d40305aec) -Note: you do not need to create a PR for this branch -- the release workflow will do that for you. +Once the branch has been created, push it to the remote repository. ### 3. If this is a patch release, cherry-pick commits for inclusion in the release into the branch. @@ -100,15 +88,14 @@ When done, run [`cargo semver-checks`](https://github.com/obi1kenobi/cargo-semve otherwise these changes will be lost when `docs-latest` is updated. ``` -# On branch `release-0.x.y` +# On branch `prepare-release-0.x.y` git fetch origin docs-latest:docs-latest git cherry-pick 0.x.z..docs-latest ``` Where `z` is the previous patch number. -Note that the `cherry-pick` will fail if there are no additional `docs-latest` commits to include, -which is fine. +Note that the `cherry-pick` will fail if there are no additional `docs-latest` commits to include, which is fine. ### 4. Update [`CHANGELOG.md`](./CHANGELOG.md). @@ -140,34 +127,40 @@ In the UI: - Set `Use workflow from` to the release branch you created in step (2). - Then choose one of the following values in the dropdown: + - `alpha` if the branch name is `release-x.y.z-alpha.N`. + This will create a one-off alpha release. - - `alpha` if the branch name is `release-x.y.z-alpha.N`. - This will create a one-off alpha release. + - `rc` if the branch name is `release-x.y.z`. + This will create a pull request for the release, and publish a release candidate. - - `rc` if the branch name is `release-x.y.z`. - This will create a pull request for the release, and publish a release candidate. - - - `final` for the final public release + - `final` for the final public release ![Image showing the Run workflow UI. It can be found at https://github.com/rerun-io/rerun/actions/workflows/release.yml](https://github.com/rerun-io/rerun/assets/1665677/6cdc8e7e-c0fc-4cf1-99cb-0749957b8328) ### 7. Wait for the workflow to finish -The PR description will contain next steps. +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. Note: there are two separate workflows running -- the one building the release artifacts, and the one running the PR checks. -You will have to wait for the [former](https://github.com/rerun-io/rerun/actions/workflows/release.yml) in order to get a link to the artifacts. +You can mostly ignore the PR checks. You will have to wait for the [former](https://github.com/rerun-io/rerun/actions/workflows/release.yml) +in order to get a link to the artifacts. ### 8. Merge changes to `main` -For minor release, merge the release branch to `main`. +The 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. -For patch release, manually create a new PR from `main` and cherry-pick the required commits. This includes at least -the `CHANLGE.log` update, plus any other changes made on the release branch that hasn't been cherry-picked in the -first place. +We want all of this to land back on `main`, so: -For alpha release, it's fine to merge **iff** the release job was successful. Otherwise, do not merge, as this would -introduce broken links in the docs. If needed, cherry-pick any commit back to `main`. +- For a minor release, merge the release branch to `main`. +- For a patch release, manually create a new PR from `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. +- For an alpha release, it's should be merged _if and only if_ the release job was successful. + Otherwise, do not merge, as this could introduce breakage across the repository, such as in documentation links. + If needed, cherry-pick any additional commits made back to `main`. ### 9. Optional: write a post mortem about the release