Release Guide

These steps describe how to conduct a release of the operator-sdk repo using example versions. Replace these versions with the current and new version you are releasing, respectively.

Table of contents:

• Major and minor releases
• Patch releases
• scorecard-test-kuttl image releases
• Release tips

Prerequisites

• git
• make
• sed

MacOS users

Install GNU sed and make which may not be by default:

brew install gnu-sed make

Major and Minor releases

We will use the v1.3.0 release version in this example.

Before starting

1. A release branch must be created and mapped before the release begins to appease the Netlify website configuration demons. You can ping SDK approvers to ensure a release branch is created prior to the release and that this mapping is created. If you have the proper permissions, you can do this by running the following, assuming the upstream SDK is the upstream remote repo:

git checkout master
git pull
git checkout -b v1.3.x
git push -u upstream v1.3.x

1. Make sure that the list of supported OLM versions stated in the Overview section of SDK docs is updated. If a new version of OLM needs to be officially supported, follow the steps in updating OLM bindata section.
2. Create and merge a commit that updates the top-level Makefile variable IMAGE_VERSION to the upcoming release tag v1.3.0. This variable ensures sample projects have been tagged correctly prior to the release commit.

sed -i -E 's/(IMAGE_VERSION = ).+/\1v1\.3\.0/g' Makefile

1. Lock down the master branch to prevent further commits before the release completes:
2. Go to Settings -> Branches in the SDK repo.
3. Under Branch protection rules, click Edit on the master branch rule.
4. In section Protect matching branches of the Rule settings box, increase the number of required approving reviewers to 6.

1. Create and push a release commit

Create a new branch to push the release commit:

export RELEASE_VERSION=v1.3.0
git checkout master
git pull
git checkout -b release-$RELEASE_VERSION

Run the pre-release make target:

make prerelease

The following changes should be present:

• changelog/generated/v1.3.0.md: commit changes (created by changelog generation).
• changelog/fragments/*: commit deleted fragment files (deleted by changelog generation).
• website/content/en/docs/upgrading-sdk-version/v1.3.0.md: commit changes (created by changelog generation).
• website/config.toml: commit changes (modified by release script).

Commit these changes and push:

git add --all
git commit -m "Release $RELEASE_VERSION"
git push -u origin release-$RELEASE_VERSION

2. Create and merge a new PR

Create and merge a new PR for the commit created in step 1. You can force-merge your PR to the locked-down master if you have admin access to the operator-sdk repo, or ask an administrator to do so.

3. Unlock the master branch

Unlock the branch by changing the number of required approving reviewers in the master branch rule back to 1.

4. Create and push a release tag

make tag
git push upstream refs/tags/$RELEASE_VERSION

5. Fast-forward the latest and release branches

The latest branch points to the latest release tag to keep the main website subdomain up-to-date. Run the following commands to do so:

git checkout latest
git reset --hard tags/$RELEASE_VERSION
git push -f upstream latest

Similarly, to update the release branch, run:

git checkout v1.3.x
git reset --hard tags/$RELEASE_VERSION
git push -f upstream v1.3.x

6. Post release steps

• Make an operator-framework Google Group post.
• Post to Kubernetes slack in #kubernetes-operators and #operator-sdk-dev.
• In the GitHub milestone, bump any open issues to the following release.

Patch releases

We will use the v1.3.1 release version in this example.

Before starting

1. Create and merge a commit that updates the top-level Makefile variable IMAGE_VERSION to the upcoming release tag v1.3.1. This variable ensures sample projects have been tagged correctly prior to the release commit.

sed -i -E 's/(IMAGE_VERSION = ).+/\1v1\.3\.1/g' Makefile

1. Lock down the v1.3.x branch to prevent further commits before the release completes:
2. Go to Settings -> Branches in the SDK repo.
3. Under Branch protection rules, click Edit on the v.* branch rule.
4. In section Protect matching branches of the Rule settings box, increase the number of required approving reviewers to 6.

1. Create and push a release commit

Create a new branch from the release branch, which should already exist for the desired minor version, to push the release commit to:

export RELEASE_VERSION=v1.3.1
git checkout v1.3.x
git pull
git checkout -b release-$RELEASE_VERSION

Run the pre-release make target:

make prerelease

The following changes should be present:

• changelog/generated/v1.3.0.md: commit changes (created by changelog generation).
• changelog/fragments/*: commit deleted fragment files (deleted by changelog generation).

Commit these changes and push:

git add --all
git commit -m "Release $RELEASE_VERSION"
git push -u origin release-$RELEASE_VERSION

2. Create and merge a new PR

Create and merge a new PR for the commit created in step 1. You can force-merge your PR to the locked-down v1.3.x if you have admin access to the operator-sdk repo, or ask an administrator to do so.

3. Unlock the v1.3.x branch

Unlock the branch by changing the number of required approving reviewers in the v.* branch rule back to 1.

4. Create and push a release tag

make tag
git push upstream refs/tags/$RELEASE_VERSION

5. Fast-forward the latest branch

The latest branch points to the latest release tag to keep the main website subdomain up-to-date. Run the following commands to do so:

git checkout latest
git reset --hard tags/$RELEASE_VERSION
git push -f upstream latest

6. Post release steps

• Make an operator-framework Google Group post.
• Post to Kubernetes slack in #kubernetes-operators and #operator-sdk-dev.
• In the GitHub milestone, bump any open issues to the following release.

Note In case there are non-transient errors while building the release job, you must:

1. Revert the release PR. To do so, create a PR which reverts step 2.
2. Fix what broke in the release branch.
3. Re-run the release with an incremented minor version to avoid Go module errors (ex. if v1.3.1 broke, then re-run the release as v1.3.2). Patch versions are cheap so this is not a big deal.

scorecard-test-kuttl image releases

The quay.io/operator-framework/scorecard-test-kuttl image is released separately from other images because it contains the kudobuilder/kuttl image, which is subject to breaking changes.

Release tags of this image are of the form: scorecard-kuttl/vX.Y.Z, where X.Y.Z is not the current operator-sdk version. For the latest version, query the operator-sdk repo tags for scorecard-kuttl/v.

The only step required is to create and push a tag. This example uses version v2.0.0, the first independent release version of this image:

export RELEASE_VERSION=scorecard-kuttl/v2.0.0
make tag
git push upstream refs/tags/$RELEASE_VERSION

The deploy/image-scorecard-test-kuttl Action workflow will build and push this image.

Helpful tips and information

Binaries and signatures

Binaries will be signed using our CI system’s GPG key. Both binary and signature will be uploaded to the release.

Release branches

Each minor release has a corresponding release branch of the form vX.Y.x, where X and Y are the major and minor release version numbers and the x is literal. This branch accepts bug fixes according to our backport policy.

Cherry-picking

Once a minor release is complete, bug fixes can be merged into the release branch for the next patch release. Fixes can be added automatically by posting a /cherry-pick v1.3.x comment in the master PR, or manually by running:

git checkout v1.3.x
git checkout -b cherrypick/some-bug
git cherry-pick <commit>
git push upstream cherrypick/some-bug

Create and merge a PR from your branch to v1.3.x.

GitHub release information

GitHub releases live under the Releases tab in the operator-sdk repo.

Updating OLM bindata

Prior to an Operator SDK release, add bindata (if required) for a new OLM version by following these steps:

1. Add the new version to the OLM_VERSIONS variable in the Makefile.
2. Remove the lowest version from that variable, as operator-sdk only supports 3 versions at a time.
3. Run make bindata.
4. Update the list of supported OLM versions stated in the Overview section of SDK documentation is updated.

Last modified March 16, 2021: add doc on updating bindata in release guide (#4638) (78ef954d)