Release Guide

This guide describes the process to create a GitHub Release for this project.

Note: These steps assume that all OSM components are being released together, including the CLI, container images, and Helm chart, all with the same version.

Release Candidates

Release candidates (RCs) should be created before each significant release so final testing can be performed. RCs are tagged as vX.Y.Z-rc.W. After the following steps have been performed to publish the RC, perform any final testing with the published release artifacts for about one week.

If issues are found, submit patches to the RC’s release branch and create a new RC with the tag vX.Y.Z-rc.W+1. Apply those same patches to the main branch. Repeat until the release is suitably stable.

Once an RC has been found to be stable, cut a release tagged vX.Y.Z using the following steps.

  1. Create a release branch
  2. Update release branch with patches and versioning changes
  3. Create and push a Git tag
  4. Add release notes
  5. Announce the new release
  6. Make version changes on main branch

Create a release branch

Look for a branch on the upstream repo named release-vX.Y, where X and Y correspond to the major and minor version of the semver tag to be used for the new release. If the branch already exists, skip to the next step.

Identify the base commit in the main branch for the release and cut a release branch off main.

$ git checkout -b release-<version> <commit-id> # ex: git checkout -b release-v0.4 0d05587

Push the release branch to the main repo (not fork), identified here by the upstream remote.

$ git push upstream release-<version> # ex: git push upstream release-v0.4

Update release branch with patches and versioning changes

Create a new branch off of the release branch to maintain updates specific to the new version.

If there are other commits on the main branch to be included in the release (such as for successive release candidates or patch releases), cherry-pick those onto this new branch.

Create a new commit on the new branch to update the hardcoded version information in the following locations:

Once patches and version information have been updated on a new branch off of the release branch, create a pull request from the new branch to the release branch. Proceed to the next step once the pull request is approved and merged.

Create and push a Git tag

Ensure your local copy of the release branch has the latest changes from the PR merged above.

Once the release is ready to be published, create and push a Git tag from the release branch to the main repo (not fork), identified here by the upstream remote.

$ export RELEASE_VERSION=<release-version> # ex: export RELEASE_VERSION=v0.4.0
$ git tag "$RELEASE_VERSION"
$ git push upstream "$RELEASE_VERSION"

A GitHub Action is triggered when the tag is pushed. It will build the CLI binaries, publish a new GitHub release, upload the packaged binaries and checksums as release assets, build and push Docker images for OSM and the demo to the openservicemesh organization on Docker Hub, and publish the Helm chart to the repo hosted at https://openservicemesh.github.io/osm.

Add release notes

In the description section of the new release, add information about feature additions, bug fixes, and any other administrative tasks completed on the repository.

Announce the new release

Make an announcement on the mailing list and Slack channel.

Make version changes on main branch

Skip this step if the release is a release candidate (RC).

Open a pull request against the main branch making the same version updates as above so the latest release assets are referenced there.

Make version changes on docs.openservicemesh.io

To add the new version to the ‘Releases’ dropdown menu on docs.openservicemesh.io, refer to this section of the site Readme.