From 2726557a6d7250cecc1aa2a7ce94d5b693146f12 Mon Sep 17 00:00:00 2001 From: Alex Leong Date: Wed, 12 Jan 2022 10:24:24 -0800 Subject: [PATCH] Add release instructions (#7574) Add instructions for releasing Linkerd Signed-off-by: Alex Leong --- RELEASE.md | 314 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 314 insertions(+) create mode 100644 RELEASE.md diff --git a/RELEASE.md b/RELEASE.md new file mode 100644 index 000000000..2bba52d82 --- /dev/null +++ b/RELEASE.md @@ -0,0 +1,314 @@ +# Linkerd2 Release + +This document contains instructions for releasing Linkerd2. + +## 1. Bump the proxy version + +Determine the commit SHA of the `linkerd2-proxy` repo to be included in the +release. If +[proxy-version](https://github.com/linkerd/linkerd2/blob/main/.proxy-version) +is already at the desired SHA, skip to step 2. + +If updating to `linkerd-proxy` HEAD, note the commit SHA at +[latest.txt](https://build.l5d.io/linkerd2-proxy/latest.txt) (Look for +`linkerd2-proxy-.tar.gz`). + +Create a new branch in the `linkerd2` repo, `username/proxy-version-bump`. + +Then run: + +```bash +bin/git-commit-proxy-version +``` + +The script will update the `.proxy-version` file. Submit a PR to obtain reviews +and approval. + +## 2. Bump the proxy-init version + +If the `linkerd2/proxy-init` project has a new release (which is rare), the +following updates are needed: + +- `go.mod` + + ```mod + github.com/linkerd/linkerd2-proxy-init v1.2.0 + ``` + +- `pkg/version/version.go` (this also implies changes in unit test fixtures) + + ```go + var ProxyInitVersion = "v1.2.0" + ``` + +- `charts/linkerd2/values.yaml` + + Upgrade the version in `global.proxyInit.image.version` + +Create a new branch in the `linkerd2` repo, +`username/proxy-init-version-bump`. + +Open a pull request that includes the changes. + +## 3. Create a minor releases branch + +**This step only applies to minor stable releases (e.g. `2.9.1`).** + +If it doesn't exist yet, create and push a branch in the `linkerd2` repo where +all the minor releases for a given major release will reside: + +```bash +git checkout -b release/2.9 +git push -u origin release/2.9 +``` + +The branch in the following step should be based off of this one. + +## 4. Create the release branch + +Create a branch in the `linkerd2` repo, `username/edge-X.X.X` (replace with +your name and the actual release number, optionally replace `edge` with +`stable`). + +## 5. Cherry pick changes from `main` + +**This step only applies to minor stable releases (e.g. `2.9.1`).** + +Locate all the commits in the git log that happened since the last stable +release, that you'd like to include in the current minor stable release, and +cherry-pick each one into the current branch using their corresponding SHAs: + +```bash +git cherry-pick ae34bcc2 +git cherry-pick b34effab +git cherry-pick 223bd232 +... +``` + +Each step might result in conflicts that you'll need to address. + +## 6. Update the Helm charts versions + +All the Helm charts (linkerd-crds, linkerd-control-plane, linkerd2-cni, +linkerd-multicluster, linkerd-jaeger and linkerd-viz) have a `version` entry +with a semver format `major.minor.patch[-edge]` that needs to be updated +according to the following rules: + +- patch bump for minor changes +- minor bump for additions/removals +- major bump for backwards-incompatible changes, most notably changes that + change the structure of `values.yaml` + +Note that edge releases require the `-edge` suffix, which should be removed when +releasing stable releases. + +Also note that the `appVersion` entry (for those charts that have it) is handled +automatically by CI. + +Finally, keep in mind chart version changes require updating the charts README +files (through `bin/helm-docs`) and golden files (through `go test ./... +-update`). + +### linkerd-crds + +Almost all the charts are always updated, at least because the docker image +versions referred in their templates change with each release. One exception is +`linkerd-crds`, which doesn't contain image references. So this chart only +requires bumping its `version` if there were changes in its templates files. + +## 7. Update the release notes + +On this branch, add the release notes for this version in `CHANGES.md`. + +Note: To see all of the changes since the previous release, run the command +below in the `linkerd2` repo. If the last release was a stable release, be +sure to use `stable-Y.Y.Y` instead of `edge-Y.Y.Y`. + +```bash +git log edge-Y.Y.Y..HEAD +``` + +And this command in the `linkerd2-proxy` repo: + +```bash +git log release/vX.X.X..release/vY.Y.Y +``` + +Where `release/vX.X.X` is the version of the proxy from the last release +and `release/vY.Y.Y` is the version of the proxy for this release, e.g.: + +```bash +git log release/v2.102.0..release/v2.103.0 +``` + +## 8. Post a PR that includes the changes + +If you're preparing a minor release, make sure the PR's merge target is the +releases branch you created above (e.g. `releases/stable-2.9`). For the other +cases the target should just be `main`. + +This PR needs an approval from a "code owner." Feel free to ping one of the +code owners if you've gotten feedback and approvals from other team members. + +## 9. Optional: push images + +To facilitate testing (particularly for stable releases) you might want to +publish the docker images in your private repo. + +First tag the release: + +```bash +git tag stable-2.9.1 +``` + +Do *not* push this tag just yet, to avoid triggering the actual public release. + +Make sure you're logged into your Github docker registry: + +```bash +echo "$GH_PAT" | docker login ghcr.io -u $GH_USERNAME --password-stdin +``` + +Where `$GH_USERNAME` is your Github username and `$GH_PAT` is a personal access +token with enough permissions for creating Github packages. + +Then this will build the images and also push them to your personal Github +docker registry (note this implies you've already set docker buildx in your +machine, if not follow [these +instructions](https://github.com/docker/buildx#installing)): + +```bash +DOCKER_REGISTRY=ghcr.io/$GH_USERNAME DOCKER_MULTIARCH=1 DOCKER_PUSH=1 bin/docker-build +``` + +If this is the first time you push those images into your personal registry, +you'll need to go to `https://github.com/$GH_USERNAME?tab=packages` and access +the settings for each image in order to make them public. + +After having successfully pushed those images, delete the tag so you can create +it again and push it for good as explained in the following step. + +Now testers can pull the CLI binaries through this: + +```bash +DOCKER_REGISTRY=ghcr.io/$GH_USERNAME bin/docker-pull-binaries stable-2.9.1 +``` + +which will dump them under the `target/release` directory. + +Besides using those particular binaries to install Linkerd, they'll also need to +point to your registry using the `--registry` flag. Currently that flag doesn't +apply to add-ons, so you need to also recur to the `--config` flag. Currently +that only applies to Grafana: + +```bash +$ cat linkerd-overrides.yml +grafana: + enabled: true + image: + name: ghcr.io/alpeb/grafana + +$ target/release/linkerd2-cli-stable-2.9.1-darwin install --registry ghcr.io/$GH_USERNAME --config ~/tmp/linkerd-overrides.yml +``` + +## 10. Merge release notes branch, then create the release tag + +After the review has passed and the branches from step 2 and 4 have been merged, +follow the instructions below to properly create and push the release tag from +the appropriate branch. + +**Note**: The release script will create a GPG-signed tag, so users must have +GPG signing setup in their local git config. + +If performing an edge release then issue these commands. The appropriate tag +will be automatically calculated: + +```bash +git checkout main +git pull +./bin/create-release-tag edge +``` + +If performing a stable release then issue these commands instead (in this case +you need to explicitly pass the version to be released): + +```bash +git checkout main +git pull +./bin/create-release-tag stable x.x.x +``` + +In both cases follow the instructions on screen for pushing the tag upstream. + +That will kick off a CI Release workflow run that will: + +- Build and push the docker images for the tag that was created +- Run the k3d integration tests in the Github actions VMs themselves +- Run a k3d integration test on a separate ARM64 host +- Create a release in Github, and upload the CLI binaries with their checksums +- Dispatch an event caught by the website repo that triggers a website rebuild + which will update the edge/stable versions in the website +- Retrieve the installation script from [run.linkerd.io](https://run.linkerd.io) + and verify it installs the current version being released +- Deploy the updated helm charts + +You can locate the CI run [here](https://github.com/linkerd/linkerd2/actions). + +## 11. Do a walkthrough verification of the release + +Go to the release page in Github and check that the notes are properly +formatted and the files are there. Download the file for your system along +with its checksum, verify the checksum matches, and do a basic sanity check: + +```bash +linkerd version +linkerd install | kubectl apply -f - +linkerd check +linkerd viz install | kubectl apply -f - +linkerd viz check +linkerd dashboard +``` + +- Install linkerd onto your cluster, and run a few CLI commands +- Open the dashboard and click around +- Click through to Grafana +- When finished with this step, you may want to delete your `alias` to prevent + confusion later + +## 12. Send the announcement email + +Send an email to cncf-linkerd-dev@lists.cncf.io, +cncf-linkerd-users@lists.cncf.io, and cncf-linkerd-announce@lists.cncf.io, +announcing the release. + +Subscribe to these mailing lists if you aren't on them: + +- [linkerd-users](https://lists.cncf.io/g/cncf-linkerd-users/join) +- [linkerd-announce](https://lists.cncf.io/g/cncf-linkerd-announce/join) +- [linkerd-dev](https://lists.cncf.io/g/cncf-linkerd-dev/join) + +Include the full release notes in the email. Liberally apply emoji. ⭐ + +## 13. Send an announcement to Linkerd Slack's #announcements channel + +Ensure that you send a brief summary of the release in Linkerd Slack's +[#announcement](https://linkerd.slack.com/messages/C0JV5E7BR) channel. + +## 14. Add a community page announcement to the website repo + +When doing a `stable-X.X.X` be sure to also include an announcement page for +the Linkerd2 dashboard "Community" sidebar button. + +In the [website](https://github.com/linkerd/website) repo: + +1. Run `hugo new --contentDir linkerd.io/content/dashboard/ YYYYMMDD.md` +2. Open the newly created file in your favorite editor and change the `title` + to match the announcement email title. +3. Remove the `draft: true` section in the file and then add a brief summary + of the stable release. +4. cd to the directory `linkerd.io`. +5. Run `hugo serve` in the directory to test your changes. +6. Verify your change by navigating to `http://localhost:1313/dashboard`. Make + sure that the announcement appears at the top of the page. +7. Once you are satisfied with your changes, Post the PR for review. + Once merged, the change should deploy automatically.