velero/site/content/docs/main/release-instructions.md

title, layout

title	layout
Release Instructions	docs

This page covers the steps to perform when releasing a new version of Velero.

Preparing for a release

(GA Only) Create release blog post

For each major or minor release, create and publish a blog post to let folks know what's new.

What to include in a release blog:

• Thank all contributors for their involvement in the release.
  • Where possible shoutout folks by name or consider spotlighting new maintainers.
• Highlight the themes, or areas of focus, for the release. Some examples of themes are security, bug fixes, feature improvements. See past Velero release blog posts for more examples.
• Include summaries of new features or workflows introduced in a release.
  • This can also include new project initiatives, like a code-of-conduct update.
  • Consider creating additional blog posts that go through new features in more detail. Plan to publish additional blogs after the release blog (all blogs don’t have to be publish all at once).

Release blog post PR:

• Prepare a PR containing the release blog post. Read the website guidelines for more information on creating a 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.
• Plan to publish this blog the same day as the release.

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

Release steps

Once you have done the prep steps, use the steps below to perform a 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 for a dry-run, without pushing to GitHub.

4. Run /hack/release-tools/tag-release.sh publish and follow the instructions when everything looks good to publish to GitHub and create the release.

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

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

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

8. Publish the release.

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

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

11. Update Homebrew version. 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.

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

Announce a release

Once you are finished doing the release, let the rest of the world know its available by posting messages in the following places.

1. Velero's Twitter account. Maintainers are encouraged to help spread the word by posting or reposting on social media.
2. Community Slack channel.
3. Google group message.

What to include:

• Thank all contributors
• A brief list of highlights in the release
• Link to the release blog post, release notes, and/or github release page