velero/site/docs/master/release-instructions.md

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. Set a variable with the full Velero version export VELERO_VERSION=v<MAJOR>.<MINOR>.<PATCH>[-beta.1]. This will be used throughout the whole process.
2. In a branch, create the file changelogs/CHANGELOG-<major>.<minor>.md (if it doesn't already exist) by copying the most recent one.
3. Run make changelog to generate a list of all unreleased changes. Copy/paste the output into CHANGELOG-<major>.<minor>.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.
4. (GA Only) Remove all changelog files from changelogs/unreleased.
5. 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".
6. If there is an existing set of pre-release versioned docs for the version you are releasing (i.e. site/docs/v1.4-pre exists, and you're releasing v1.4.0-beta.2 or v1.4.0):
   • Remove the directory containing the pre-release docs, i.e. site/docs/<pre-release-version>.
   • Delete the pre-release docs table of contents file, i.e. site/_data/<pre-release-version>-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.
7. Run NEW_DOCS_VERSION=v<major.minor> make gen-docs (e.g. NEW_DOCS_VERSION=v1.2 make gen-docs or NEW_DOCS_VERSION=v1.2-pre make gen-docs).
   • Note that:
     • NEW_DOCS_VERSION defines the version that the docs will be tagged with (i.e. what's in the URL, what shows up in the version dropdown on the site). This should be formatted as either v1.4 (for a GA release), or v1.4-pre (for an alpha/beta/RC).
     • VELERO_VERSION defines the tag of Velero that any https://github.com/vmware-tanzu/velero/... links in the docs should redirect to.
8. Follow the additional instructions at site/README-JEKYLL.md to complete the docs generation process.
9. Do a review of the diffs, and/or run make serve-docs and review the site.
10. 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?scopes=repo.
2. Choose a name for your token.
3. Click "Generate token".
4. 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.
2. Click on the name of the relevant token.
3. Click "Regenerate token".
4. 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.

2. Set your GitHub token as an environment variable. export GITHUB_TOKEN=<your token value>

3. Run /hack/release-tools/tag-release.sh and follow the instructions.

4. Navigate to the draft GitHub release, at https://github.com/vmware-tanzu/velero/releases.

5. 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.

6. 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.

7. Publish the release.

8. 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

9. (GA Only) Merge the blog post PR.

10. 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)

Post-release - Homebrew version update

From a Mac, you can run brew bump-formula-pr to create a new PR with the updated release's information.

To make sure it's the most up-to-date:

1. If you don't already have one, create a GitHub access token for Homebrew
2. Run export HOMEBREW_GITHUB_API_TOKEN=your_token_here on your command line to make sure that brew can work on GitHub on your behalf.
3. Run hack/brew-update.sh. This script will download the necessary files, do the checks, and invoke the brew helper to submit the PR, which will open in your browser.

Post-release - Windows Chocolatey version update

From a Windows computer, follow the step-by-step instructions to create the Windows Chocolatey package for Velero CLI