Skip to content

Latest commit

 

History

History
190 lines (135 loc) · 12.5 KB

release_guide.md

File metadata and controls

190 lines (135 loc) · 12.5 KB
Raw
title description type
Release Guide
OSM Release Guide
docs

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.

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

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. See here for additional information.

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

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.

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

Add changes to be backported

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.

$ 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.

$ git cherry-pick <commit-id> # ex: git cherry-pick 1bdc75a

Fix any merge conflicts and change the commit message to begin with [backport]:

[backport] allow exporting access log to OTEL collector # previously - telemetry: allow exporting access log to OTEL collector

Push your changes to your branch.

$ git push <local-repo> <patch-branch-name>

Create a pull request to backport the changes to the release branch, see example PR. Use a merge commit instead of a squash commit when merging to preserve the original commits.

Create and push the pre-release Git tag

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.

$ PRE_RELEASE_VERSION=<pre-release-version> # ex: PRE_RELEASE_VERSION=pre-rel-v0.4.0
$ git tag "$PRE_RELEASE_VERSION"
$ git push upstream "$PRE_RELEASE_VERSION"

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

A note about FIPS

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.

Update release branch with patches and versioning changes

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 charts/osm/values.yaml 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.
  • The chart and app version in charts/osm/Chart.yaml to the release version.
  • The Helm chart README.md
    • Necessary changes should be made automatically by running make chart-readme
  • If this the first release on a new release branch, update the upgrade e2e test 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=release_pull_request_template.md. Alternatively, copy the raw template from release_pull_request_template.md.

Proceed to the next step once the pull request is approved and merged, see example PR.

Create and push the release 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

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.

Update documentation and docs.openservicemesh.io website

1. Create the release specific branch in osm-docs repo

If a branch corresponding to the Major.Minor version is not available in the osm-docs 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:

  1. Do not create a branch for patch releases. The same documentation is used for patches having the same Major.Minor version.
  2. 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.

2. Update version references to the latest version for the given Major.Minor version

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 https://github.com/openservicemesh/osm-docs/blob/main/README.md/#update-the-release-references. Image tags pinned to a specific version must also be updated in the demo manifests.

3. Update API reference documentation

Follow the Generating API Reference Documentation guide to update the API references on the docs site.

4. Update error code documentation

On the docs site's main branch, edit the file https://github.com/openservicemesh/osm-docs/blob/main/content/en/docs/guides/troubleshooting/control_plane_error_codes.md to update the OSM error code table.

  1. Build OSM on the release branch.

  2. 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.                          |

  3. Copy the table and replace the existing table in the file https://github.com/openservicemesh/osm-docs/blob/main/content/en/docs/guides/troubleshooting/control_plane_error_codes.md.

  4. If there were updates to the table, make a PR in the OSM docs repository.

Announce the new release

Make an announcement on the OSM mailing list and OSM Slack channel after you join CNCF Slack.

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 to update the version field in charts/osm/Chart.yaml to the release version.

Workflow Diagram

Here is a diagram to illustrate the git branching strategy and workflow in the release process:

OSM git branching strategy