Skip to content

Latest commit

 

History

History
144 lines (97 loc) · 4.24 KB

RELEASE.md

File metadata and controls

144 lines (97 loc) · 4.24 KB
Raw

Release cheatsheet

The CI handles most of the release process. All that is required is pushing a tag in the form of v{semver}. Where {semver} is a semantic version (e.g. 0.1.3). This may include a pre-release part (e.g. 0.1.3-alpha.1).

Important

The CI will check if the version of the tag matches the version of the crates. If they don't align, the release build will fail. See below for more information.

What we promise

Right now everything is in flux. We do not make any promises on the API (internal Rust APIs or external HTTP APIs).

We simply release 0.x versions as we see fit. And it is ok to directly go from an alpha pre-release to a proper release. We don't honor the semver promises (sorry).

Right now, we use the following pre-release modifiers (this might change in the future):

  • alpha – for any pre-release
  • rc – for something we plan to properly release

We also don't publish to crates.io, only release a tag, binary artifacts and container images.

For 1.0.0 and beyond, this should work differently. Maybe even before. However, there are no plans for that yet.

Pre-requisites

  • You have some common developer tools for Rust installed (e.g. cargo, git)
  • Your local main branch is in sync with the upstream main branch. The git remote for upstream is named upstream.
  • You have cargo release installed. This can be done using cargo install cargo-release.

Performing the release

In a nutshell, the steps are:

  • Ensure the cargo versions are aligned with the release tag that we create next
  • Re-generate the OpenAPI spec, as it contains the version
  • Tag the release
  • Push the tag

To make it clearer what got released and what is part of the next release, it makes sense to create a PR before pushing the release tag. This will also make step 1 easier for the next release, as that's already been taken care of.

The following instructions walk you through the process on the example of releasing 0.0.0-alpha.1, which you need to replace with the actual release. Note that during release process we should avoid merging any other PRs to main branch.

1. Prepare Branch

Switch to main branch and make sure your local checkout is up-to-date.

> git switch main
> git fetch --all
> git rebase upstream/main

Checkout branch to prepare release from.

> git checkout -b 0.0.0-alpha.1-prepare

Note - This is not a release branch!

2. Create Pull Request

Dry run to check that we can safely bump release.

> cargo release version 0.0.0-alpha.1

If all looks good bump release.

> cargo release version 0.0.0-alpha.1 -x

Ensure Cargo dependencies are up-to-date.

> cargo update

Normal lint check and ensure openapi up-to-date.

> cargo xtask precommit

Commit (and sign) changes.

> git commit -S -a -m"chore: prepare release 0.0.0-alpha.1"

Push commit.

> git push upstream 0.0.0-alpha.1-prepare

3. Raise PR, pass CI, review and merge

Goto github and raise PR.

PR should pass CI.

Get a friend to review.

On succesful review go ahead and merge!

4. Create release

Switch to main branch and make sure your local checkout is up-to-date.

> git switch main
> git fetch --all
> git rebase upstream/main

Create (signed) tag.

> git tag -S v0.0.0-alpha.1

Push tag which triggers github release workflow.

> git push upstream v0.0.0-alpha.1

Congratulations, the release is now building - monitor the outcome! 🎂

If things go wrong

Unaligned versions

If the current crate versions have already been released, then you need to bump the versions upfront.

Broken stuff

Technically, it is possible to make changes to the tag and just force-push it again.

However, in most cases, it might be easier to accept defeat and try again with a new version.

Test/personal release

To test, you can push a release tag to your personal fork of the repository. By default, this will run the release workflow in your personal repository, and create a release there. If that's ok for your fork, you can push and force push tags as you like, to fix and test the release process.