Skip to content
This repository was archived by the owner on Dec 11, 2021. It is now read-only.

Latest commit

 

History

History
315 lines (220 loc) · 13.4 KB

release.md

File metadata and controls

315 lines (220 loc) · 13.4 KB

Releases

Making an Operator SDK release involves:

  • Updating CHANGELOG.md.
  • Tagging and signing a git commit and pushing the tag to GitHub.
  • Building a release binary and signing the binary
  • Creating a release by uploading binary, signature, and CHANGELOG.md updates for the release to GitHub.
  • Creating a patch version branch of the form v1.2.x for major and minor releases.

Releases can only be performed by maintainers.

Dependency and platform support

Go version

Release binaries will be built with the Go compiler version specified in the Operator SDK's prerequisites section.

Kubernetes versions

As the Operator SDK interacts directly with the Kubernetes API, certain API features are assumed to exist in the target cluster. The currently supported Kubernetes version will always be listed in the SDK prerequisites section.

Operating systems and architectures

Release binaries will be built for the x86_64 architecture for both GNU Linux and MacOS Darwin platforms.

Support for the Windows platform or any architecture other than x86_64 is not on the roadmap at this time.

Binaries and signatures

Binaries will be signed using a maintainers' verified GitHub PGP key. Both binary and signature will be uploaded to the release. Ensure you import maintainer keys to verify release binaries.

Release tags

Every release will have a corresponding git semantic version tag beginning with v, ex. v1.2.3.

Make sure you've uploaded your GPG key and configured git to use that signing key either globally or for the Operator SDK repository. Tagging will be handled by release.sh.

Note: the email the key is issued for must be the email you use for git.

$ git config [--global] user.signingkey "$GPG_KEY_ID"
$ git config [--global] user.email "$GPG_EMAIL"

Release Notes

Release notes should thoroughly describe changes made to code, documentation, and design of the SDK. PR links should be included wherever possible.

The following sections, often directly copied from our changelog, are used as release notes:

[Version as title, ex. v1.2.3]

### Added
- [Short description of feature added] (#PR)
...

### Changed
- [Short description of change made] (#PR)
...

### Deprecated
- [Short description of feature deprecated] (#PR)
...

### Removed
- [Short description of feature removed] (#PR)
...

### Bug Fixes
- [Short description of bug and fix] (#PR)
...

Release Signing

When a new release is created, the tag for the commit it signed with a maintainers' gpg key and the binaries for the release are also signed by the same key. All keys used by maintainers will be available via public PGP keyservers such as pool.sks-keyservers.net.

For new maintainers who have not done a release and do not have their PGP key on a public keyserver, output your armored public key using this command:

$ gpg --armor --export "$GPG_EMAIL" > mykey.asc

Then, copy and paste the content of the outputted file into the Submit a key section on pool.sks-keyservers.net or any other public keyserver that synchronizes the key to other public keyservers. Once that is done, other people can download your public key and you are ready to sign releases.

Verifying a release

To verify a git tag signature, use this command:

$ git verify-tag --verbose "$TAG_NAME"

To verify a release binary using the provided asc files, place the binary and corresponding asc file into the same directory and use the corresponding command:

# macOS
$ gpg --verify operator-sdk-${RELEASE_VERSION}-x86_64-apple-darwin.asc
# GNU/Linux
$ gpg --verify operator-sdk-${RELEASE_VERSION}-x86_64-linux-gnu.asc

If you do not have the maintainers public key on your machine, you will get an error message similar to this:

$ git verify-tag ${TAG_NAME}
gpg: Signature made Wed 31 Oct 2018 02:57:31 PM PDT
gpg:                using RSA key 4AEE18F83AFDEB23
gpg: Cant check signature: public key not found

To download the key, use this command, replacing $KEY_ID with the RSA key string provided in the output of the previous command:

$ gpg --recv-key "$KEY_ID"

Now you should be able to verify the tags and/or binaries.

Release steps

These steps describe how to conduct a release of the SDK, upgrading from v1.2.0 to v1.3.0. Replace these versions with the current and new version you are releasing, respectively.

Note: master should be frozen between steps 1 and 3 so that all commits will be either in the new release or have a pre-release version, ex. v1.2.0+git. Otherwise commits might be built into a release that shouldn't or have an incorrect version, which makes debugging user issues difficult.

(Patch release only) Cherry-picking to a release branch

As more than one patch may be created per minor release, branch names of the form v1.3.x are created after a minor version is released. Bug fixes will be merged into the release branch only after testing.

Add fixes to the release branch by doing the following:

$ git checkout v1.3.x
$ git checkout -b release-v1.3.1
$ git cherry-pick "$GIT_COMMIT_HASH" # Usually from master
$ git push origin release-v1.3.1

Create a PR from release-v1.3.1 to v1.3.x. Once CI passes and your PR is merged, continue to step 1.

1. Create a PR for release version and CHANGELOG.md updates

Once all PR's needed for a release have been merged, branch from master:

$ git checkout master
$ git pull

If making a patch release, check out the corresponding minor version branch:

$ git checkout v1.2.x
$ git pull

Create a new branch to push release commits:

$ git checkout -b release-v1.3.0

Commit changes to the following files:

  • version/version.go: update Version to v1.3.0.
  • internal/pkg/scaffold/gopkgtoml.go, under the [[constraint]] for github.com/operator-framework/operator-sdk:
    • Comment out branch = "master"
    • Un-comment version = "v1.2.0"
    • Change v1.2.0 to v1.3.0
  • internal/pkg/scaffold/gopkgtoml_test.go: same as for internal/pkg/scaffold/gopkgtoml.go.
  • internal/pkg/scaffold/ansible/gopkgtoml.go: same as for internal/pkg/scaffold/gopkgtoml.go.
  • internal/pkg/scaffold/helm/gopkgtoml.go: same as for internal/pkg/scaffold/gopkgtoml.go.
  • internal/pkg/scaffold/go_mod.go, in the replace block for github.com/operator-framework/operator-sdk:
    • Add the following replace entry: github.com/operator-framework/operator-sdk => github.com/operator-framework/operator-sdk v1.3.0.
    • If an entry already exists, change the version to v1.3.0.
  • internal/pkg/scaffold/go_mod_test.go: same as for internal/pkg/scaffold/go_mod.go.
  • internal/pkg/scaffold/helm/go_mod.go: same as for internal/pkg/scaffold/go_mod.go.
  • internal/pkg/scaffold/ansible/go_mod.go: same as for internal/pkg/scaffold/go_mod.go.
  • CHANGELOG.md: update the ## Unreleased header to ## v1.3.0.

Create a new PR for release-v1.3.0.

2. Create a release tag, binaries, and signatures

The top-level release.sh script will take care of verifying versions in files described in step 1, and tagging and verifying the tag, as well as building binaries and generating signatures by calling make release.

Call the script with the only argument being the new SDK version:

$ ./release.sh v1.3.0

Release binaries and signatures will be in build/. Both binary and signature file names contain version, architecture, and platform information; signature file names correspond to the binary they were generated from suffixed with .asc. For example, signature file operator-sdk-v1.3.0-x86_64-apple-darwin.asc was generated from a binary named operator-sdk-v1.3.0-x86_64-apple-darwin. To verify binaries and tags, see the verification section.

Note: you must have both git and gpg default PGP keys set locally for release.sh to run without error. Additionally you must add your PGP key to a public-key-server.

Push tag v1.3.0 upstream:

$ git push --tags

Once this tag passes CI, go to step 3. For more info on tagging, see the release tags section.

Note: If CI fails for some reason, you will have to revert the tagged commit, re-commit, and make a new PR.

3. Create a PR for post-release version and CHANGELOG.md updates

Check out a new branch from master (or use your release-v1.3.0) and commit the following changes:

  • version/version.go: update Version to v1.3.0+git.

  • internal/pkg/scaffold/gopkgtoml.go, under the [[constraint]] for github.com/operator-framework/operator-sdk:

    • Comment out version = "v1.3.0"
    • Un-comment branch = "master"

  • internal/pkg/scaffold/gopkgtoml_test.go: same as for internal/pkg/scaffold/gopkgtoml.go.

  • internal/pkg/scaffold/ansible/gopkgtoml.go: same as for internal/pkg/scaffold/gopkgtoml.go.

  • internal/pkg/scaffold/helm/gopkgtoml.go: same as for internal/pkg/scaffold/gopkgtoml.go.

  • CHANGELOG.md: add the following as a new set of headers above ## v1.3.0:

    ## Unreleased

### Added

### Changed

### Deprecated

### Removed

### Bug Fixes

Create a new PR for this branch. Once this PR passes CI and is merged, master can be unfrozen.

4. Releasing binaries, signatures, and release notes

The final step is to upload binaries, their signature files, and release notes from CHANGELOG.md.

Note: if this is a pre-release, make sure to check the This is a pre-release box under the file attachment frame. If you are not sure what this means, ask another maintainer.

  1. Go to the SDK release page and click the Draft a new release button in the top right corner.
  2. Select the tag version v1.3.0, and set the title to v1.3.0.
  3. Copy and paste any CHANGELOG.md under the v1.3.0 header that have any notes into the description form.
  4. Attach all binaries and .asc signature files to the release by dragging and dropping them.
  5. Click the Publish release button.

You've now fully released a new version of the Operator SDK. Good work! However, there is one more step that needs to be completed: making a release branch to allow us to make patch fixes for this release.

5. Making a new release branch

If you have created a new major or minor release, you need to make a new branch for it. To do this, checkout the tag that you created and make a new branch that matches the version you released with x in the position of the patch number. For example, to make a new release branch after v1.3.0 and push it to the repo, you would follow these steps:

$ git checkout tags/v1.3.0
Note: checking out 'tags/v1.3.0'.
...
$ git checkout -b v1.3.x
Switched to a new branch 'v1.3.x'
$ git push origin v1.3.x
Total 0 (delta 0), reused 0 (delta 0)
remote:
remote: Create a pull request for 'v1.3.x' on GitHub by visiting:
remote:      https://github.com/operator-framework/operator-sdk/pull/new/v1.3.x
remote:
To github.com:operator-framework/operator-sdk.git
 * [new branch]      v1.3.x -> v1.3.x

Now that the branch exists, you need to make the post-release PR for the new release branch. To do this, simply follow the same steps as in step 3 with the addition of changing the branch name in the gopkgtoml scaffold from master to the new branch (for example, v1.3.x). Then, make the PR against the new branch.

6. Updating the Homebrew formula

We support installing via Homebrew, so we need to update the operator-sdk Homebrew formula once the release is cut. Follow the instructions below, or for more detailed ones on the Homebrew contribution README, to open a PR against the repository.

docker run -t -d linuxbrew/brew:latest
docker exec -it <CONTAINER_ID> /bin/bash`
# Run the following commands in the container.
git config --global github.name <GITHUB-USERNAME>
git config --global github.token <GITHUB-TOKEN>
# Replace the release version of the newly cut release.
OPERATORSDKURL=https://github.com/operator-framework/operator-sdk/archive/<RELEASE-VERSION>.tar.gz
curl $OPERATORSDKURL -o operator-sdk
# Calculate the SHA256
OPERATORSUM="$(sha256sum operator-sdk | cut -d ' ' -f 1)"
brew bump-formula-pr --strict --url=$OPERATORSDKURL --sha256=$OPERATORSUM operator-sdk

Note: If there were any changes made to the CLI commands, make sure to look at the existing tests, in case they need updating.