Project: Open Service Mesh (Orchestration & Management / Service Mesh)
File: release_guide.md

title: "Release Guide" description: "OSM Release Guide" type: docs 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. Once an RC has been found to be stable, cut a release tagged `vX.Y.Z` using the following steps. - - - - - - - - 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`. See for additional information. 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`. ```console $ git checkout -b release-<version> <commit-id> # ex: git checkout -b release-v0.4 0d05587 ``` Note: Care must be taken to ensure the release branch is created from a commit meant for the release. If unsure about the commit to use to create the release branch, please open an issue in the `osm` repo and a maintainer will assist you with this. Push the release branch to the upstream repo (NOT forked), identified here by the `upstream` remote. ```console $ git push upstream release-<version> # ex: git push upstream release-v0.4 ``` Create a new branch off of the release branch to maintain updates specific to the new version. Let's call it the patch branch. The patch branch should not be created in the upstream repo. ```console $ git checkout upstream/release-<version> # ex: git checkout upstream/release-v1.2 $ git switch -c <patch-branch-name> # Create the patch branch in your repo ``` 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 the patch branch. ```console $ git cherry-pick <commit-id> # ex: git cherry-pick 1bdc75a ``` Fix any merge conflicts and change the commit message to begin with [backport]: ```bash [backport] allow exporting access log to OTEL collector # previously - telemetry: allow exporting access log to OTEL collector ``` Push your changes to your branch. ```console $ git push <local-repo> <patch-branch-name> ``` Create a pull request to backport the changes to the release branch, see . Use a merge commit instead of a squash commit when merging to preserve the original

The pre-release Git tag publishes the OSM control plane images to the `openservicemesh` organization in Dockerhub, and publishes the image digests as an artifact of the pre-release Github workflow. The image digests must be used in the next step to update the default control plane image referenced in the Helm charts. The pre-release Git tag is of the form `pre-rel-<release-version>`, e.g. `pre-rel-v0.4.0`. ```console $ PRERELEASEVERSION=<pre-release-version> # ex: PRERELEASEVERSION=pre-rel-v0.4.0 $ git tag "$PRERELEASEVERSION" $ git push upstream "$PRERELEASEVERSION" ``` Once the pre-release Git tag has been pushed, wait for the Pre-release Github workflow to complete. Upon workflow completion, retrieve the image digests for the given release. The image digests are logged in the "Image digests" step of the Pre-release workflow. The image digest logs contain the sha256 image digest for each control plane image as follows: ``` init: sha256:96bdf7c283ac679344ab1bc5badc406ff486ad2fecb46b209e11e19d2a0a4d3c osm-controller: sha256:069f20906035d9b8c4c59792ee1f2b90586a6134a5e286bf015af8ee83041510 osm-injector: sha256:d2e96d99a311b120c4afd7bd3248f75d0766c98bd121a979a343e438e9cd2c35 osm-crds: sha256:359a4a6b031d0f72848d6bedc742b34b60323ebc5d5001071c0695130b694efd osm-bootstrap: sha256:fd159fdb965cc0d3d7704afaf673862b5e92257925fc3f6345810f98bb6246f8 ``` The previous step will create and push AMD64-based Docker images for the FIPS version of the OSM control plane to DockerHub. Because GitHub Actions doesn't support remote hosted ARM runners, FIPS ARM images for OSM will only be available via Microsoft Artifact Registry. Create a new commit on the patch branch to update the hardcoded version information in the following locations: The control plane image digests defined by `osm.image.digest` for images in from the image digests obtained from the Pre-release workflow. For example, if the osm-controller image digest is `sha256:eb194138abddbe271d42b290489917168a6a891a3dabb575de02c53f13879bee`, update the value of `osm.image.digest.osmController` to `sha256:eb194138abddbe271d42b290489917168a6a891a3dabb575de02c53f13879bee`. Ensure the value for `osm.image.tag` in is set to the empty string. The chart and app version in to the release version. The Helm chart Necessary changes should be made automatically by running `make chart-readme` If this the first release on a new release branch, update the install version from `i.Version = ">0.0.0-0"` to the previous minor release. e.g. When cutting the release-v1.1 branch, this should be updated to `"1.0"`. Once patches and version information have been updated on the patch branch off of the release branch, create a pull request from the patch branch to the release branch. When creating your pull request, generate the release checklist for the description by adding the following to the PR URL: `?expand=1&template=releasepullrequest_template.md`. Alternatively, copy the raw template from . Proceed to the next step once the pull request is approved and merged, see . 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. ```console $ export

# ex: export RELEASEVERSION=v0.4.0 $ git tag "$RELEASE_VERSION" $ git push upstream "$RELEASE_VERSION" ``` A 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 on Docker Hub, and publish the Helm chart to the repo hosted at https://openservicemesh.github.io/osm. The release job runs the `scripts/release-notes.sh` script to generate release notes for the specific release tag. Update the `Notable Changes` and `Deprecation Notes` section based on notable feature additions, critical bug fixes, and deprecated functionality. If a branch corresponding to the Major.Minor version is not available in the repo, create it based on https://github.com/openservicemesh/osm-docs/blob/main/README.md#adding-release-specific-docs. For example, to publish the documentation for v0.10.0, there must exist a release-v0.10 branch in the `osm-docs` repo. *Note: Do not create a branch for patch releases. The same documentation is used for patches having the same Major.Minor version. Care must be taken to ensure the release branch is created from a commit that meant for the release. If unsure about the commit to use to create the release branch, please open an issue in the `osm-docs` repo and a maintainer will assist you with this. For example, when v0.10.1 is being released, update all of the version references from v0.10.0 to v0.10.1 to reflect the latest documentation for the Major.Minor version. Instructions for updating the release version references can be found at . Image tags pinned to a specific version must also be updated in the demo manifests. Follow the guide to update the API references on the docs site. On the docs site's main branch, edit the file to update the OSM error code table. Build OSM on the release branch. Generate the mapping of OSM error codes and their descriptions using the `osm support` cli tool. ``` ./bin/osm support error-info ++-+ | ERROR CODE | DESCRIPTION | ++-+ | E1000 | An invalid command line argument was passed to the application. | ++-+ | E1001 | The specified log level could not be set in the system. | ``` Copy the table and replace the existing table in the file . If there were updates to the table, make a PR in the OSM docs repository. Make an announcement on the and after you . Skip this step if the release is a release candidate (RC). Open a pull request against the `main` branch to update the `version` field in `charts/osm/Chart.yaml` to the release version. Here is a diagram to illustrate the git branching strategy and workflow in the release process: