From 0704c77ba133d2882d8318c651c80257a2142f01 Mon Sep 17 00:00:00 2001 From: Steve Kriss Date: Fri, 15 Nov 2019 19:18:44 -0700 Subject: [PATCH] release instructions (#2052) * release instructions Signed-off-by: Steve Kriss * edits Signed-off-by: Steve Kriss * add announce locations Signed-off-by: Steve Kriss --- site/docs/master/release-instructions.md | 80 ++++++++++++++++++++++++ 1 file changed, 80 insertions(+) create mode 100644 site/docs/master/release-instructions.md diff --git a/site/docs/master/release-instructions.md b/site/docs/master/release-instructions.md new file mode 100644 index 000000000..c249a62ee --- /dev/null +++ b/site/docs/master/release-instructions.md @@ -0,0 +1,80 @@ +# Release Instructions + +## Ahead of Time + +### (GA Only) Release Blog Post PR + +Prepare a PR containing the release blog post. It's usually easiest to make a copy of the most recent existing post, then replace the content as appropriate. + +You also need to update `site/index.html` to have "Latest Release Information" contain a link to the new post. + +### (Pre-Release and GA) Changelog and Docs PR + +1. In a branch, create the file `changelogs/CHANGELOG-..md` (if it doesn't already exist) by copying the most recent one. +1. Run `make changelog` to generate a list of all unreleased changes. Copy/paste the output into `CHANGELOG-..md`, under the "All Changes" section for the release. + - You *may* choose to tweak formatting on the list of changes by adding code blocks, etc. +1. (GA Only) Remove all changelog files from `changelogs/unreleased`. +1. Update the main `CHANGELOG.md` file to properly reference the release-specific changelog file: + - (Pre-Release) List the release under "Development release" + - (GA) List the release under "Current release", remove any pre-releases from "Development release", and move the previous release into "Older releases". +1. If there is an existing set of pre-release versioned docs for the version you are releasing (i.e. `site/docs/v1.2.0-beta.1` exists, and you're releasing `v1.2.0-beta.2` or `v1.2.0`): + - Remove the directory containing the pre-release docs, i.e. `site/docs/`. + - Delete the pre-release docs table of contents file, i.e. `site/_data/-toc.yml`. + - Remove the pre-release docs table of contents mapping entry from `site/_data/toc-mapping.yml`. + - Remove all references to the pre-release docs from `site/_config.yml`. +1. Run `NEW_DOCS_VERSION= make gen-docs` (e.g. `NEW_DOCS_VERSION=v1.2.0 make gen-docs` or `NEW_DOCS_VERSION=v1.2.0-beta.1 make gen-docs`). +1. Follow the additional instructions at `site/README-JEKYLL.md` to complete the docs generation process. +1. Do a review of the diffs, and/or run `make serve-docs` and review the site. +1. Submit a PR containing the changelog and the version-tagged docs. + +### (Pre-Release and GA) GitHub Token + +To run the `goreleaser` process to generate a GitHub release, you'll need to have a GitHub token. See https://goreleaser.com/environment/ for more details. + +You may regenerate the token for every release if you prefer. + +#### If you don't already have a token +1. Go to https://github.com/settings/tokens/new. +1. Choose a name for your token. +1. Check the "repo" scope. +1. Click "Generate token". +1. Save the token value somewhere - you'll need it during the release, in the `GITHUB_TOKEN` environment variable. + +#### If you do already have a token, but need to regenerate it +1. Go to https://github.com/settings/tokens. +1. Click on the name of the relevant token. +1. Click "Regenerate token". +1. Save the token value somewhere - you'll need it during the release, in the `GITHUB_TOKEN` environment variable. + +## During Release + +This process is the same for both pre-release and GA, except for the fact that there will not be a blog post PR to merge for pre-release versions. + +1. Merge the changelog + docs PR, so that it's included in the release tag. +1. Make sure your working directory is clean: `git status` should show `nothing to commit, working tree clean`. +1. Run `git fetch upstream master && git checkout upstream/master`. +1. Run `git tag ` (e.g. `git tag v1.2.0` or `git tag v1.2.0-beta.1`). +1. Run `git push upstream ` (e.g. `git push upstream v1.2.0` or `git push upstream v1.2.0-beta.1`). This will trigger the Travis CI job that builds/publishes the Docker images. +1. Generate the GitHub release (it will be created in "Draft" status, which means it's not visible to the outside world until you click "Publish"): + + ```bash + GITHUB_TOKEN=your-github-token \ + RELEASE_NOTES_FILE=changelogs/CHANGELOG-..md \ + PUBLISH=true \ + make release + ``` + +1. Navigate to the draft GitHub release, at https://github.com/vmware-tanzu/velero/releases. +1. If this is a patch release (e.g. `v1.2.1`), note that the full `CHANGELOG-1.2.md` contents will be included in the body of the GitHub release. You need to delete the previous releases' content (e.g. `v1.2.0`'s changelog) so that only the latest patch release's changelog shows. +1. Do a quick review for formatting. **Note:** the `goreleaser` process should detect if it's a pre-release version, and check that box in the GitHub release appropriately, but it's always worth double-checking. +1. Publish the release. +1. By now, the Docker images should have been published. Perform a smoke-test - for example: + - Download the CLI from the GitHub release + - Use it to install Velero into a cluster (or manually update an existing deployment to use the new images) + - Verify that `velero version` shows the expected output + - Run a backup/restore and ensure it works +1. (GA Only) Merge the blog post PR. +1. Announce the release: + - Twitter (mention a few highlights, link to the blog post) + - Slack channel + - Google group (this doesn't get a lot of traffic, and recent releases may not have been posted here)