github.com/dmvolod/operator-sdk@v0.8.2/doc/dev/release.md (about) 1 # Releases 2 3 Making an Operator SDK release involves: 4 5 - Updating `CHANGELOG.md`. 6 - Tagging and signing a git commit and pushing the tag to GitHub. 7 - Building a release binary and signing the binary 8 - Creating a release by uploading binary, signature, and `CHANGELOG.md` updates for the release to GitHub. 9 - Creating a patch version branch of the form `v1.2.x` for major and minor releases. 10 11 Releases can only be performed by [maintainers][doc-maintainers]. 12 13 ## Dependency and platform support 14 15 ### Go version 16 17 Release binaries will be built with the Go compiler version specified in the Operator SDK's [prerequisites section][doc-readme-prereqs]. 18 19 ### Kubernetes versions 20 21 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][doc-readme-prereqs]. 22 23 ### Operating systems and architectures 24 25 Release binaries will be built for the `x86_64` architecture for both GNU Linux and MacOS Darwin platforms. 26 27 Support for the Windows platform or any architecture other than `x86_64` is not on the roadmap at this time. 28 29 ## Binaries and signatures 30 31 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. 32 33 ## Release tags 34 35 Every release will have a corresponding git semantic version tag beginning with `v`, ex. `v1.2.3`. 36 37 Make sure you've [uploaded your GPG key][link-github-gpg-key-upload] and configured git to [use that signing key][link-git-config-gpg-key] either globally or for the Operator SDK repository. Tagging will be handled by `release.sh`. 38 39 **Note:** the email the key is issued for must be the email you use for git. 40 41 ```bash 42 $ git config [--global] user.signingkey "$GPG_KEY_ID" 43 $ git config [--global] user.email "$GPG_EMAIL" 44 ``` 45 46 ## Release Notes 47 48 Release notes should thoroughly describe changes made to code, documentation, and design of the SDK. PR links should be included wherever possible. 49 50 The following sections, often directly copied from our [changelog][doc-changelog], are used as release notes: 51 52 ```Markdown 53 [Version as title, ex. v1.2.3] 54 55 ### Added 56 - [Short description of feature added] (#PR) 57 ... 58 59 ### Changed 60 - [Short description of change made] (#PR) 61 ... 62 63 ### Deprecated 64 - [Short description of feature deprecated] (#PR) 65 ... 66 67 ### Removed 68 - [Short description of feature removed] (#PR) 69 ... 70 71 ### Bug Fixes 72 - [Short description of bug and fix] (#PR) 73 ... 74 ``` 75 76 ## Release Signing 77 78 When a new release is created, the tag for the commit it signed with a maintainers' gpg key and 79 the binaries for the release are also signed by the same key. All keys used by maintainers will 80 be available via public PGP keyservers such as pool.sks-keyservers.net. 81 82 For new maintainers who have not done a release and do not have their PGP key on a public 83 keyserver, output your armored public key using this command: 84 85 ```sh 86 $ gpg --armor --export "$GPG_EMAIL" > mykey.asc 87 ``` 88 89 Then, copy and paste the content of the outputted file into the `Submit a key` section on 90 pool.sks-keyservers.net or any other public keyserver that synchronizes 91 the key to other public keyservers. Once that is done, other people can download your public 92 key and you are ready to sign releases. 93 94 ## Verifying a release 95 96 To verify a git tag, use this command: 97 98 ```sh 99 $ git verify-tag --verbose "$TAG_NAME" 100 ``` 101 102 If you do not have the mantainers public key on your machine, you will get an error message similiar to this: 103 104 ```sh 105 git verify-tag --verbose "$TAG_NAME" 106 object 61e0c23e9d2e217f8d95ac104a8f2545c102b5c3 107 type commit 108 tag v0.6.0 109 tagger Ish Shah <ishah@redhat.com> 1552688145 -0700 110 111 Operator SDK v0.6.0 112 gpg: Signature made Fri Mar 15 23:15:45 2019 CET 113 gpg: using RSA key <KEY_ID> 114 gpg: Can't check signature: No public key 115 ``` 116 117 To download the key, use the following command, replacing `$KEY_ID` with the RSA key string provided in the output of the previous command: 118 119 ```sh 120 $ gpg --recv-key "$KEY_ID" 121 ``` 122 123 To verify a release binary using the provided asc files see the [installation guide.][install-guide] 124 125 ## Release steps 126 127 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. 128 129 **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. 130 131 ### (Patch release only) Cherry-picking to a release branch 132 133 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. 134 135 Add fixes to the release branch by doing the following: 136 137 ```bash 138 $ git checkout v1.3.x 139 $ git checkout -b release-v1.3.1 140 $ git cherry-pick "$GIT_COMMIT_HASH" # Usually from master 141 $ git push origin release-v1.3.1 142 ``` 143 144 Create a PR from `release-v1.3.1` to `v1.3.x`. Once CI passes and your PR is merged, continue to step 1. 145 146 ### 1. Create a PR for release version and CHANGELOG.md updates 147 148 Once all PR's needed for a release have been merged, branch from `master`: 149 150 ```sh 151 $ git checkout master 152 $ git pull 153 ``` 154 155 If making a patch release, check out the corresponding minor version branch: 156 157 ```sh 158 $ git checkout v1.2.x 159 $ git pull 160 ``` 161 162 Create a new branch to push release commits: 163 164 ```sh 165 $ git checkout -b release-v1.3.0 166 ``` 167 168 Commit changes to the following files: 169 170 - `version/version.go`: update `Version` to `v1.3.0`. 171 - `internal/pkg/scaffold/gopkgtoml.go`, under the `[[constraint]]` for `github.com/operator-framework/operator-sdk`: 172 - Comment out `branch = "master"` 173 - Un-comment `version = "v1.2.0"` 174 - Change `v1.2.0` to `v1.3.0` 175 - `internal/pkg/scaffold/gopkgtoml_test.go`: same as for `internal/pkg/scaffold/gopkgtoml.go`. 176 - `internal/pkg/scaffold/ansible/gopkgtoml.go`: same as for `internal/pkg/scaffold/gopkgtoml.go`. 177 - `internal/pkg/scaffold/helm/gopkgtoml.go`: same as for `internal/pkg/scaffold/gopkgtoml.go`. 178 - `internal/pkg/scaffold/go_mod.go`, in the `replace` block for `github.com/operator-framework/operator-sdk`: 179 - Add the following `replace` entry: `github.com/operator-framework/operator-sdk => github.com/operator-framework/operator-sdk v1.3.0`. 180 - If an entry already exists, change the version to `v1.3.0`. 181 - `internal/pkg/scaffold/go_mod_test.go`: same as for `internal/pkg/scaffold/go_mod.go`. 182 - `internal/pkg/scaffold/helm/go_mod.go`: same as for `internal/pkg/scaffold/go_mod.go`. 183 - `internal/pkg/scaffold/ansible/go_mod.go`: same as for `internal/pkg/scaffold/go_mod.go`. 184 - `CHANGELOG.md`: update the `## Unreleased` header to `## v1.3.0`. 185 - `doc/user/install-operator-sdk.md`: update the linux and macOS URLs to point to the new release URLs. 186 187 Create a new PR for `release-v1.3.0`. 188 189 ### 2. Create a release tag, binaries, and signatures 190 191 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`. 192 193 Call the script with the only argument being the new SDK version: 194 195 ```sh 196 $ ./release.sh v1.3.0 197 ``` 198 199 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](#verifying-a-release). 200 201 **Note:** you must have both [`git`][doc-git-default-key] and [`gpg`][doc-gpg-default-key] default PGP keys set locally for `release.sh` to run without error. Additionally you must add your PGP key to a [public-key-server](#release-signing). 202 203 Push tag `v1.3.0` upstream: 204 205 ```sh 206 $ git push --tags 207 ``` 208 209 Once this tag passes CI, go to step 3. For more info on tagging, see the [release tags section](#release-tags). 210 211 **Note:** If CI fails for some reason, you will have to revert the tagged commit, re-commit, and make a new PR. 212 213 ### 3. Create a PR for post-release version and CHANGELOG.md updates 214 215 Check out a new branch from master (or use your `release-v1.3.0`) and commit the following changes: 216 217 - `version/version.go`: update `Version` to `v1.3.0+git`. 218 - `internal/pkg/scaffold/gopkgtoml.go`, under the `[[constraint]]` for `github.com/operator-framework/operator-sdk`: 219 - Comment out `version = "v1.3.0"` 220 - Un-comment `branch = "master"` 221 - `internal/pkg/scaffold/gopkgtoml_test.go`: same as for `internal/pkg/scaffold/gopkgtoml.go`. 222 - `internal/pkg/scaffold/ansible/gopkgtoml.go`: same as for `internal/pkg/scaffold/gopkgtoml.go`. 223 - `internal/pkg/scaffold/helm/gopkgtoml.go`: same as for `internal/pkg/scaffold/gopkgtoml.go`. 224 - `CHANGELOG.md`: add the following as a new set of headers above `## v1.3.0`: 225 226 ```markdown 227 ## Unreleased 228 229 ### Added 230 231 ### Changed 232 233 ### Deprecated 234 235 ### Removed 236 237 ### Bug Fixes 238 ``` 239 240 Create a new PR for this branch. Once this PR passes CI and is merged, `master` can be unfrozen. 241 242 ### 4. Releasing binaries, signatures, and release notes 243 244 The final step is to upload binaries, their signature files, and release notes from `CHANGELOG.md`. 245 246 **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. 247 248 1. Go to the SDK [release page][release-page] and click the `Draft a new release` button in the top right corner. 249 1. Select the tag version `v1.3.0`, and set the title to `v1.3.0`. 250 1. Copy and paste any `CHANGELOG.md` under the `v1.3.0` header that have any notes into the description form. 251 1. Attach all binaries and `.asc` signature files to the release by dragging and dropping them. 252 1. Click the `Publish release` button. 253 254 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. 255 256 ### 5. Making a new release branch 257 258 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: 259 260 ```console 261 $ git checkout tags/v1.3.0 262 Note: checking out 'tags/v1.3.0'. 263 ... 264 $ git checkout -b v1.3.x 265 Switched to a new branch 'v1.3.x' 266 $ git push origin v1.3.x 267 Total 0 (delta 0), reused 0 (delta 0) 268 remote: 269 remote: Create a pull request for 'v1.3.x' on GitHub by visiting: 270 remote: https://github.com/operator-framework/operator-sdk/pull/new/v1.3.x 271 remote: 272 To github.com:operator-framework/operator-sdk.git 273 * [new branch] v1.3.x -> v1.3.x 274 ``` 275 276 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](#3-create-a-pr-for-post-release-version-and-changelogmd-updates) 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. 277 278 ### 6. Updating the Homebrew formula 279 280 We support installing via [Homebrew][homebrew], so we need to update the operator-sdk [Homebrew formula][homebrew-formula] once the release is cut. Follow the instructions below, or for more detailed ones on the Homebrew contribution [README][homebrew-readme], to open a PR against the [repository][homebrew-repo]. 281 282 283 ``` 284 docker run -t -d linuxbrew/brew:latest 285 docker exec -it <CONTAINER_ID> /bin/bash` 286 # Run the following commands in the container. 287 git config --global github.name <GITHUB-USERNAME> 288 git config --global github.token <GITHUB-TOKEN> 289 # Replace the release version of the newly cut release. 290 OPERATORSDKURL=https://github.com/operator-framework/operator-sdk/archive/<RELEASE-VERSION>.tar.gz 291 curl $OPERATORSDKURL -o operator-sdk 292 # Calculate the SHA256 293 OPERATORSUM="$(sha256sum operator-sdk | cut -d ' ' -f 1)" 294 brew bump-formula-pr --strict --url=$OPERATORSDKURL --sha256=$OPERATORSUM operator-sdk 295 ``` 296 297 Note: If there were any changes made to the CLI commands, make sure to look at the existing tests, in case they need updating. 298 299 [install-guide]:../user/install-operator-sdk.md 300 [doc-maintainers]:../../MAINTAINERS 301 [doc-readme-prereqs]:../../README.md#prerequisites 302 [doc-git-default-key]:https://help.github.com/en/articles/telling-git-about-your-signing-key 303 [doc-gpg-default-key]:https://lists.gnupg.org/pipermail/gnupg-users/2001-September/010163.html 304 [link-github-gpg-key-upload]:https://github.com/settings/keys 305 [link-git-config-gpg-key]:https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work 306 [doc-changelog]:../../CHANGELOG.md 307 [release-page]:https://github.com/operator-framework/operator-sdk/releases 308 [homebrew]:https://brew.sh/ 309 [homebrew-formula]:https://github.com/Homebrew/homebrew-core/blob/master/Formula/operator-sdk.rb 310 [homebrew-readme]:https://github.com/Homebrew/homebrew-core/blob/master/CONTRIBUTING.md#to-submit-a-version-upgrade-for-the-foo-formula 311 [homebrew-repo]:https://github.com/Homebrew/homebrew-core