Project: Operator Framework (App Definition and Development / Application Definition & Image Build)
File: releasing.md

title: Release Guide linkTitle: Releasing weight: 4 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. The following tools and permissions are needed to conduct a release of the operator-sdk repo. : version 2.2+ : version 4.2+ : version 4.3+ Must be a Must be an admin on the To install the prerequisite tools on MacOS, complete the following steps: Install GNU `sed` and `make`, which may not be installed by default: ```sh brew install gnu-sed make ``` Verify that the version of `make` is higher than 4.2 using command `make --version`. Add the gnubin directory for `make` to your PATH from your `~/.bashrc` to allow you to use `gmake` as `make`: ```sh echo 'export PATH="/usr/local/opt/make/libexec/gnubin:$PATH"' >> ~/.bashrc ``` Verify that the version of `sed` is higher than 4.3 using command `gnu-sed --version`. Add the gnubin directory for `gnu-sed` to your PATH from your `~/.bashrc` to allow you to use `gnu-sed` as `sed`: ```sh echo 'export PATH="/usr/local/opt/gnu-sed/libexec/gnubin:$PATH"' >> ~/.bashrc ``` We will use the `v1.3.0` release version in this example. Be sure to substitute the version you are releasing into the provided commands. To perform a major or minor release, you must perform the following actions: Ensure a new Netlify branch is created Create a release branch and lock down the master branch Create and merge a PR for the release branch Unlock the master branch and push a release tag to it Perform some clean up actions and announce the new release to the community Before creating a new release branch, it is imperative to perform the following initial setup steps: In the pane in Netlify, click into the Additional branches list section and add `v1.13.x`. This will watch the branch when there are changes on Github (creating the branch, or adding a commit). NOTE: You must be a in order to edit the branches list. Create a release branch by running the following, assuming the upstream SDK repo is the `upstream` remote on your machine: ```sh git checkout master git fetch upstream master git pull master git checkout -b v1.3.x git push upstream v1.3.x ``` Make sure that the list of supported OLM versions is up to date: Identify if a new version of OLM needs to be officially supported by ensuring that the latest three releases listed on the are all listed as supported in the section of the SDK docs. If a new version of OLM needs to be added and an old version removed, follow the steps in the section before moving onto the next step. Lock down the `master` branch to prevent further commits before the release completes: Go to `Settings -> Branches` in the SDK repo. Under `Branch protection rules`, click `Edit` on the `master` branch rule. In section `Protect matching branches` of the `Rule settings` box, increase the number of required approving reviewers to

Scroll down to save your changes to protect the `master` branch. Create and push a release commit Create a new branch to push the release commit: ```sh export RELEASE_VERSION=v1.3.0 git checkout master git pull master git checkout -b release-$RELEASE_VERSION ``` Update 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. ```sh sed -i -E 's/(IMAGE_VERSION = ).+/\1v1\.3\.0/g' Makefile ``` If this command fails on MacOS with a warning "sed is not found", follow the step 5 in the section to map `gsed` to `sed`. Run the pre-release `make` target: ```sh make prerelease ``` The following changes should be present: `Makefile`: IMAGE_VERSION should be modified to the upcoming release tag. (This variable ensures sampleprojects have been tagged correctly prior to the release commit.) `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). `testdata/*`: Generated sample code. Commit these changes and push to your remote (assuming your remote is named `origin`): ```sh git add Makefile changelog website testdata git commit -sm "Release $RELEASE_VERSION" git push origin release-$RELEASE_VERSION ``` Create and merge a new PR for the release-v1.3.0 branch created in step 5.4. 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. Note that the docs PR check will fail because the site isn't published yet; the PR can be merged anyways. Unlock the `master` branch Go to `Settings -> Branches` in the SDK repo. Under `Branch protection rules`, click `Edit` on the `master` branch rule. In section `Protect matching branches` of the `Rule settings` box, reduce the number of required approving reviewers back to 1. Create and push a release tag on `master` Refresh your local `master` branch, tag the release PR commit, and push to the main operator-sdk repo (assumes the remote's name is `upstream`): ```sh git checkout master git pull master make tag git push upstream refs/tags/$RELEASE_VERSION ``` 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: ```sh git checkout latest git reset --hard refs/tags/$RELEASE_VERSION git push -f upstream latest ``` Similarly, to update the release branch, run: ```sh git checkout v1.3.x git reset --hard refs/tags/$RELEASE_VERSION git push -f upstream v1.3.x ``` Post release steps Publish the new Netlify subdomain for version-specific docs. Assuming that the Netlify prestep was done before the new branch was created, a new should be visible to Netlify Admins under Domain management > Branch subdomains and can be mapped to a subdomain. (Note: you may have to scroll down to the bottom of the Branch subdomains section to find the branch that is ready to be

Please test that this subdomain works by going to the link in a browser. You can use the link in the second column to jump to the docs page for this release. Make an post. You can use as an example. Post to Kubernetes slack in #kubernetes-operators and #operator-sdk-dev. You can use as an example. Clean up the GitHub milestone In the , bump any open issues to the following release. Close out the milestone. Update the newly unsupported branch documentation (1.1.x in this example)to mark it as archived. (Note that this step does not need to be merged before the release is complete.) Checkout the newly unsupported release branch: ```sh git checkout v1.1.x ``` Modify the `website/config.toml` file on lines 88-90 to be the following: ```toml version = "v1.1" archived_version = true urllatestversion = "https://sdk.operatorframework.io" ``` We will use the `v1.3.1` release version in this example. Lock down the `v1.3.x` branch to prevent further commits before the release completes: Go to `Settings -> Branches` in the SDK repo. Under `Branch protection rules`, click `Edit` on the `v*.` branch rule. In section `Protect matching branches` of the `Rule settings` box, increase the number of required approving reviewers to `6`. Create a new branch from the release branch (v1.3.x in this example). This branch should already exist prior to cutting a patch release. ```sh export RELEASE_VERSION=v1.3.1 git checkout v1.3.x git pull git checkout -b release-$RELEASE_VERSION ``` Using the version for your release as the IMAGE_VERSION, execute the following commands from the root of the project. ```sh sed -i -E 's/(IMAGE_VERSION = ).+/\1v1\.3\.1/g' Makefile make prerelease ``` All of the following changes should be present (and no others). Makefile: IMAGE_VERSION should be modified to the upcoming release tag. (This variable ensures sampleprojects have been tagged correctpy priror to the release commit.) changelog/: all fragments should be deleted and consolidated into the new file `changelog/generated/v1.3.1.md` docs: If there are migration steps, a new migration doc will be created. The installation docs should also contain a link update. testdata/: Generated samples and tests should have version bumps Commit these changes and push these changes to your fork: ```sh git add Makefile changelog website testdata git commit -sm "Release $RELEASE_VERSION" git push -u origin release-$RELEASE_VERSION ``` Create a pull request against the `v1.3.x` branch. Once approving review is given, merge. You may have to unlock the branch by setting "required approving reviewers" to back to `1`. (See step 0). Pull down `v1.3.x` and tag it. ```sh git checkout v1.3.x git pull upstream v1.3.x make tag git push upstream refs/tags/$RELEASE_VERSION ``` If the patch release is on the latest y-stream (in the example you would not ff latest if there was a y-stream for v1.4.x), you will need to fast-forward the `latest` git branch. (The `latest` branch points to the latest release tag to keep the main website subdomain up-to-date.) ```sh git checkout latest git reset --hard tags/$RELEASE_VERSION git push -f upstream latest ``` Make an post. Post to Kubernetes slack in #kubernetes-operators

#operator-sdk-dev. In the , bump any open issues to the following release. Note In case there are non-transient errors while building the release job, you must: Revert the release PR. To do so, create a PR which reverts the patch release PR created in step . Fix what broke in the release branch. 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. The `quay.io/operator-framework/scorecard-test-kuttl` image is released separately from other images because it contains the 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 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: ```sh export RELEASE_VERSION=scorecard-kuttl/v2.0.0 make tag git push upstream refs/tags/$RELEASE_VERSION ``` The Action workflow will build and push this image. Binaries will be signed using our CI system's GPG key. Both binary and signature will be uploaded to the release. 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 . 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: ```sh 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 releases live under the in the operator-sdk repo. Prior to an Operator SDK release, add bindata (if required) for a new OLM version by following these steps: Add the new version to the variable in the Makefile. Remove the lowest version from that variable, as `operator-sdk` only supports 3 versions at a time. Run `make bindata`. Check that all files were correctly updated by running this script from the root directory of the repository: ```sh ./hack/check-olm.sh ``` If the check shows that files were missed by the make target, manually edit them to add the new version and remove the obsolete version. Check that the list of supported OLM versions stated in the section of SDK documentation is updated. Add the changed files to ensure that they will be committed as part of the release commit: ```sh git add -u ``` The following should be considered when doing parallel patch releases: Releasing in order is nice but not worth the inconvenience. Release order affects the order on GitHub releases, and which is labeled "latest release". Do not unlock v.* branches while other releases are in progress. Instead, have an admin do the merges. Release announcements should be consolidated.