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-<major>.<minor>.md (if it doesn’t already exist) by copying the most recent one.
2. 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.
3. (GA Only) Remove all changelog files from changelogs/unreleased.
4. 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”.
5. 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.
6. Run NEW_DOCS_VERSION=v<major.minor> VELERO_VERSION=v<full-version> make gen-docs (e.g. NEW_DOCS_VERSION=v1.2 VELERO_VERSION=v1.2.0 make gen-docs or NEW_DOCS_VERSION=v1.2-pre VELERO_VERSION=v1.2.0-beta.1 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.
7. Follow the additional instructions at site/README-JEKYLL.md to complete the docs generation process.
8. Do a review of the diffs, and/or run make serve-docs and review the site.
9. 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.
2. Choose a name for your token.
3. Check the “repo” scope.
4. Click “Generate token”.
5. 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. Make sure your working directory is clean: git status should show nothing to commit, working tree clean.

3. Run git fetch upstream main && git checkout upstream/main.

4. Run git tag <VERSION> (e.g. git tag v1.2.0 or git tag v1.2.0-beta.1).

5. Run git push upstream <VERSION> (e.g. git push upstream v1.2.0 or git push upstream v1.2.0-beta.1). This will trigger the github action that builds/publishes the Docker images.

6. 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”):

   GITHUB_TOKEN=your-github-token \
   RELEASE_NOTES_FILE=changelogs/CHANGELOG-<major>.<minor>.md \
   PUBLISH=true \
   make release
   

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

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

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

10. Publish the release.

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

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

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