github.com/rakanixu/helm@v2.8.2+incompatible/docs/release-checklist.md (about) 1 # Release Checklist 2 3 **IMPORTANT**: If your experience deviates from this document, please document the changes to keep it up-to-date. 4 5 ## A Maintainer's Guide to Releasing Helm 6 7 So you're in charge of a new release for helm? Cool. Here's what to do... 8 9 ![TODO: Nothing](../images/nothing.png) 10 11 Just kidding! :trollface: 12 13 All releases will be of the form vX.Y.Z where X is the major version number, Y is the minor version number and Z is the patch release number. This project strictly follows [semantic versioning](http://semver.org/) so following this step is critical. 14 15 It is important to note that this document assumes that the git remote in your repository that corresponds to "https://github.com/kubernetes/helm" is named "upstream". If yours is not (for example, if you've chosen to name it "origin" or something similar instead), be sure to adjust the listed snippets for your local environment accordingly. If you are not sure what your upstream remote is named, use a command like `git remote -v` to find out. 16 17 If you don't have an upstream remote, you can add one easily using something like: 18 19 ```shell 20 git remote add upstream git@github.com:kubernetes/helm.git 21 ``` 22 23 In this doc, we are going to reference a few environment variables as well, which you may want to set for convenience. For major/minor releases, use the following: 24 25 ```shell 26 export RELEASE_NAME=vX.Y.0 27 export RELEASE_BRANCH_NAME="release-$RELEASE_NAME" 28 export RELEASE_CANDIDATE_NAME="$RELEASE_NAME-rc1" 29 ``` 30 31 If you are creating a patch release, you may want to use the following instead: 32 33 ```shell 34 export PREVIOUS_PATCH_RELEASE=vX.Y.Z 35 export RELEASE_NAME=vX.Y.Z+1 36 export RELEASE_BRANCH_NAME="release-X.Y" 37 export RELEASE_CANDIDATE_NAME="$RELEASE_NAME-rc1" 38 ``` 39 40 ## 1. Create the Release Branch 41 42 ### Major/Minor Releases 43 44 Major releases are for new feature additions and behavioral changes *that break backwards compatibility*. Minor releases are for new feature additions that do not break backwards compatibility. To create a major or minor release, start by creating a `release-vX.Y.0` branch from master. 45 46 ```shell 47 git fetch upstream 48 git checkout upstream/master 49 git checkout -b $RELEASE_BRANCH_NAME 50 ``` 51 52 This new branch is going to be the base for the release, which we are going to iterate upon later. 53 54 ### Patch releases 55 56 Patch releases are a few critical cherry-picked fixes to existing releases. Start by creating a `release-vX.Y.Z` branch from the latest patch release. 57 58 ```shell 59 git fetch upstream --tags 60 git checkout $PREVIOUS_PATCH_RELEASE 61 git checkout -b $RELEASE_BRANCH_NAME 62 ``` 63 64 From here, we can cherry-pick the commits we want to bring into the patch release: 65 66 ```shell 67 # get the commits ids we want to cherry-pick 68 git log --oneline 69 # cherry-pick the commits starting from the oldest one, without including merge commits 70 git cherry-pick -x <commit-id> 71 git cherry-pick -x <commit-id> 72 ``` 73 74 This new branch is going to be the base for the release, which we are going to iterate upon later. 75 76 ## 2. Change the Version Number in Git 77 78 When doing a minor release, make sure to update pkg/version/version.go with the new release version. 79 80 ```shell 81 $ git diff pkg/version/version.go 82 diff --git a/pkg/version/version.go b/pkg/version/version.go 83 index 2109a0a..6f5a1a4 100644 84 --- a/pkg/version/version.go 85 +++ b/pkg/version/version.go 86 @@ -26,7 +26,7 @@ var ( 87 // Increment major number for new feature additions and behavioral changes. 88 // Increment minor number for bug fixes and performance enhancements. 89 // Increment patch number for critical fixes to existing releases. 90 - Version = "v2.6" 91 + Version = "v2.7" 92 93 // BuildMetadata is extra build time data 94 BuildMetadata = "unreleased" 95 ``` 96 97 The README stores links to the latest release for helm. We want to change the version to the first release candidate which we are releasing (more on that in step 5). 98 99 ```shell 100 $ git diff README.md 101 diff --git a/README.md b/README.md 102 index 022afd79..547839e2 100644 103 --- a/README.md 104 +++ b/README.md 105 @@ -34,10 +34,10 @@ Think of it like apt/yum/homebrew for Kubernetes. 106 107 Binary downloads of the Helm client can be found at the following links: 108 109 -- [OSX](https://kubernetes-helm.storage.googleapis.com/helm-v2.7.0-darwin-amd64.tar.gz) 110 -- [Linux](https://kubernetes-helm.storage.googleapis.com/helm-v2.7.0-linux-amd64.tar.gz) 111 -- [Linux 32-bit](https://kubernetes-helm.storage.googleapis.com/helm-v2.7.0-linux-386.tar.gz) 112 -- [Windows](https://kubernetes-helm.storage.googleapis.com/helm-v2.7.0-windows-amd64.tar.gz) 113 +- [OSX](https://kubernetes-helm.storage.googleapis.com/helm-v2.8.0-darwin-amd64.tar.gz) 114 +- [Linux](https://kubernetes-helm.storage.googleapis.com/helm-v2.8.0-linux-amd64.tar.gz) 115 +- [Linux 32-bit](https://kubernetes-helm.storage.googleapis.com/helm-v2.8.0-linux-386.tar.gz) 116 +- [Windows](https://kubernetes-helm.storage.googleapis.com/helm-v2.8.0-windows-amd64.tar.gz) 117 118 Unpack the `helm` binary and add it to your PATH and you are good to go! 119 macOS/[homebrew](https://brew.sh/) users can also use `brew install kubernetes-helm`. 120 ``` 121 122 For patch releases, the old version number will be the latest patch release, so just bump the patch number, incrementing Z by one. 123 124 ```shell 125 git add . 126 git commit -m "bump version to $RELEASE_CANDIDATE_NAME" 127 ``` 128 129 ## 3. Commit and Push the Release Branch 130 131 In order for others to start testing, we can now push the release branch upstream and start the test process. 132 133 ```shell 134 git push upstream $RELEASE_BRANCH_NAME 135 ``` 136 137 Make sure to check [helm on CircleCI](https://circleci.com/gh/kubernetes/helm) and make sure the release passed CI before proceeding. 138 139 If anyone is available, let others peer-review the branch before continuing to ensure that all the proper changes have been made and all of the commits for the release are there. 140 141 ## 4. Create a Release Candidate 142 143 Now that the release branch is out and ready, it is time to start creating and iterating on release candidates. 144 145 ```shell 146 git tag --sign --annotate "${RELEASE_CANDIDATE_NAME}" --message "Helm release ${RELEASE_CANDIDATE_NAME}" 147 git push upstream $RELEASE_CANDIDATE_NAME 148 ``` 149 150 CircleCI will automatically create a tagged release image and client binary to test with. 151 152 For testers, the process to start testing after CircleCI finishes building the artifacts involves the following steps to grab the client from Google Cloud Storage: 153 154 linux/amd64, using /bin/bash: 155 156 ```shell 157 wget https://kubernetes-helm.storage.googleapis.com/helm-$RELEASE_CANDIDATE_NAME-linux-amd64.tar.gz 158 ``` 159 160 darwin/amd64, using Terminal.app: 161 162 ```shell 163 wget https://kubernetes-helm.storage.googleapis.com/helm-$RELEASE_CANDIDATE_NAME-darwin-amd64.tar.gz 164 ``` 165 166 windows/amd64, using PowerShell: 167 168 ```shell 169 PS C:\> Invoke-WebRequest -Uri "https://kubernetes-helm.storage.googleapis.com/helm-$RELEASE_CANDIDATE_NAME-windows-amd64.tar.gz" -OutFile "helm-$ReleaseCandidateName-windows-amd64.tar.gz" 170 ``` 171 172 Then, unpack and move the binary to somewhere on your $PATH, or move it somewhere and add it to your $PATH (e.g. /usr/local/bin/helm for linux/macOS, C:\Program Files\helm\helm.exe for Windows). 173 174 ## 5. Iterate on Successive Release Candidates 175 176 Spend several days explicitly investing time and resources to try and break helm in every possible way, documenting any findings pertinent to the release. This time should be spent testing and finding ways in which the release might have caused various features or upgrade environments to have issues, not coding. During this time, the release is in code freeze, and any additional code changes will be pushed out to the next release. 177 178 During this phase, the $RELEASE_BRANCH_NAME branch will keep evolving as you will produce new release candidates. The frequency of new candidates is up to the release manager: use your best judgement taking into account the severity of reported issues, testers' availability, and the release deadline date. Generally speaking, it is better to let a release roll over the deadline than to ship a broken release. 179 180 Each time you'll want to produce a new release candidate, you will start by adding commits to the branch by cherry-picking from master: 181 182 ```shell 183 git cherry-pick -x <commit_id> 184 ``` 185 186 You will also want to update the release version number and the CHANGELOG as we did in steps 2 and 3 as separate commits. 187 188 After that, tag it and notify users of the new release candidate: 189 190 ```shell 191 export RELEASE_CANDIDATE_NAME="$RELEASE_NAME-rc2" 192 git tag --sign --annotate "${RELEASE_CANDIDATE_NAME}" --message "Helm release ${RELEASE_CANDIDATE_NAME}" 193 git push upstream $RELEASE_CANDIDATE_NAME 194 ``` 195 196 From here on just repeat this process, continuously testing until you're happy with the release candidate. 197 198 ## 6. Finalize the Release 199 200 When you're finally happy with the quality of a release candidate, you can move on and create the real thing. Double-check one last time to make sure eveything is in order, then finally push the release tag. 201 202 ```shell 203 git checkout $RELEASE_BRANCH_NAME 204 git tag --sign --annotate "${RELEASE_NAME}" --message "Helm release ${RELEASE_NAME}" 205 git push upstream $RELEASE_NAME 206 ``` 207 208 ## 7. Write the Release Notes 209 210 We will auto-generate a changelog based on the commits that occurred during a release cycle, but it is usually more beneficial to the end-user if the release notes are hand-written by a human being/marketing team/dog. 211 212 If you're releasing a major/minor release, listing notable user-facing features is usually sufficient. For patch releases, do the same, but make note of the symptoms and who is affected. 213 214 An example release note for a minor release would look like this: 215 216 ```markdown 217 ## vX.Y.Z 218 219 Helm vX.Y.Z is a feature release. This release, we focused on <insert focal point>. Users are encouraged to upgrade for the best experience. 220 221 The community keeps growing, and we'd love to see you there. 222 223 - Join the discussion in [Kubernetes Slack](https://slack.k8s.io/): 224 - `#helm-users` for questions and just to hang out 225 - `#helm-dev` for discussing PRs, code, and bugs 226 - Hang out at the Public Developer Call: Thursday, 9:30 Pacific via [Zoom](https://zoom.us/j/4526666954) 227 - Test, debug, and contribute charts: [GitHub/kubernetes/charts](https://github.com/kubernetes/charts) 228 229 ## Installation and Upgrading 230 231 Download Helm X.Y. The common platform binaries are here: 232 233 - [OSX](https://storage.googleapis.com/kubernetes-helm/helm-vX.Y.Z-darwin-amd64.tar.gz) 234 - [Linux](https://storage.googleapis.com/kubernetes-helm/helm-vX.Y.Z-linux-amd64.tar.gz) 235 - [Windows](https://storage.googleapis.com/kubernetes-helm/helm-vX.Y.Z-windows-amd64.tar.gz) 236 237 Once you have the client installed, upgrade Tiller with `helm init --upgrade`. 238 239 The [Quickstart Guide](https://docs.helm.sh/using_helm/#quickstart-guide) will get you going from there. For **upgrade instructions** or detailed installation notes, check the [install guide](https://docs.helm.sh/using_helm/#installing-helm). You can also use a [script to install](https://raw.githubusercontent.com/kubernetes/helm/master/scripts/get) on any system with `bash`. 240 241 ## What's Next 242 243 - vX.Y.Z+1 will contain only bug fixes. 244 - vX.Y+1.Z is the next feature release. This release will focus on ... 245 246 ## Changelog 247 248 - chore(*): bump version to v2.7.0 08c1144f5eb3e3b636d9775617287cc26e53dba4 (Adam Reese) 249 - fix circle not building tags f4f932fabd197f7e6d608c8672b33a483b4b76fa (Matthew Fisher) 250 ``` 251 252 The changelog at the bottom of the release notes can be generated with this command: 253 254 ```shell 255 PREVIOUS_RELEASE=vX.Y.Z 256 git log --no-merges --pretty=format:'- %s %H (%aN)' $RELEASE_NAME $PREVIOUS_RELEASE 257 ``` 258 259 Once finished, go into GitHub and edit the release notes for the tagged release with the notes written here. 260 261 ## 9. Evangelize 262 263 Congratulations! You're done. Go grab yourself a $DRINK_OF_CHOICE. You've earned it. 264 265 After enjoying a nice $DRINK_OF_CHOICE, go forth and announce the glad tidings of the new release in Slack and on Twitter. You should also notify any key partners in the helm community such as the homebrew formula maintainers, the owners of incubator projects (e.g. ChartMuseum) and any other interested parties. 266 267 Optionally, write a blog post about the new release and showcase some of the new features on there!