Project: Velero (Runtime / Cloud Native Storage)
File: release-instructions.md

title: "Release Instructions" layout: docs toc: "true" This page covers the steps to perform when releasing a new version of Velero. Please read the documented variables in each script to understand what they are for and how to properly format their values. You will need to have an upstream remote configured to use to the repository. You can check this using `git remote -v`. The release script () will use `upstream` as the default remote name if it is not specified using the environment variable `REMOTE`. GA release: major and minor releases only. Example: 1.0 (major), 1.5 (minor). Pre-releases: Any release leading up to a GA. Example: 1.4.0-beta.1, 1.5.0-rc.1 RC releases: Release Candidate, contains everything that is supposed to ship with the GA release. This is still a pre-release. Velero is on a "train leaves the station" model for releases. We will generate a release candidate (RC) at the scheduled time. Multiple release candidates may be generated, depending on if bugs are found during testing. When testing has passed a release build will be generated. The release candidate commit must meet the following criteria: No major bugs outstanding Unit tests pass E2E tests against latest Kubernetes on AWS, vSphere and kind pass Once the release has moved to RC, a code freeze is in effect. Only changes needed to release are allowable. In order for a release candidate to be released, it must meet the following criteria: Unit tests pass E2E tests against latest K8S and earliest supported K8S on Azure, vSphere, Kind, AWS, GCP Manual tests pass (manual tests will be converted to automated testing) When bugs are identified by any of these methods, we will determine whether the bug is a release blocker or not and a fix generated if it is. When release blocker bugs identifies in an release candidate are fixed, another RC will be generated and the test cycle will restart. For each major or minor release, create and publish a blog post to let folks know what's new. Please follow these . If you encounter the error `You don't have enough free space in /var/cache/apt/archives/` when running `make serve-docs`: run `docker system prune`. If it doesn't already exist: in a branch, create the file `changelogs/CHANGELOG-<major>.<minor>.md` by copying the most recent one. Update the file `changelogs/CHANGELOG-<major>.<minor>.md` 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. Update links at the top of the file to point to the new release version Update the main `CHANGELOG.md` file to properly reference the release-specific changelog file Under "Current release": Should contain only the current GA

Under "Development release": Should contain only the latest pre-release Move any prior pre-release into "Older releases" GA Only: Remove all changelog files from `changelogs/unreleased`. Generate new docs Run `make gen-docs`, passing the appropriate variables. Examples: a) `VELEROVERSION=v1.5.0-rc.1 NEWDOCS_VERSION=v1.5.0-rc.1 make gen-docs`. b) `VELEROVERSION=v1.5.0 NEWDOCS_VERSION=v1.5 make gen-docs`). Note: `PREVIOUSDOCSVERSION=<doc-version-to-copy-from>` is optional; when not set, it will default to the latest doc version. Clean up when there is an existing set of pre-release versioned docs for the version you are releasing Example: `site/content/docs/v1.5.0-beta.1` exists, and you're releasing `v1.5.0-rc.1` or `v1.5` Remove the directory containing the pre-release docs, i.e. `site/content/docs/<pre-release-version>`. Delete the pre-release docs table of contents file, i.e. `site/data/docs/<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`. Create the "Upgrade to $major.minor" page if it does not already exist (). If it already exists, update any usage of the previous version string within this file to use the new version string instead (). This needs to be done in both the versioned and the `main` folders. Review and submit PR Follow the additional instructions at `site/README-HUGO.md` to complete the docs generation process. Do a review of the diffs, and/or run `make serve-docs` and review the site. Submit a PR containing the changelog and the version-tagged docs. The image of velero is built based on . For the reproducibility of the release, before the release candidate is tagged, we need to make sure the in the Dockerfile on the release branch, the base image is referenced by digest, such as https://github.com/vmware-tanzu/velero/blob/release-1.7/Dockerfile#L53-L54 Pre-requisite: PR with the changelog and docs is merged, so that it's included in the release tag. This process is the same for both pre-release and GA. Refer to the above for instructions. If the dry-run fails with random errors, try running it again. Manually create the release branch on Github, in the form like `release-$major.$minor` Create a tagged release in dry-run mode This won't push anything to GitHub. Run `VELEROVERSION=v1.9.0-rc.1 REMOTE=<upstream-remote> GITHUBTOKEN=REDACTED ONRELEASEBRANCH=TRUE ./hack/release-tools/tag-release.sh`. Fix any issue. Create a tagged release and push it to GitHub Run `VELEROVERSION=v1.9.0-rc.1 REMOTE=<upstream-remote> GITHUBTOKEN=REDACTED ONRELEASEBRANCH=TRUE ./hack/release-tools/tag-release.sh publish`. Publish the release Navigate to the draft GitHub release at https://github.com/vmware-tanzu/velero/releases and edit the release. If this is a patch release (e.g. `v1.9.1`), note that the full `CHANGELOG-1.9.md` contents will be included in the body of the GitHub release. You need to delete the previous releases' content (e.g. `v1.9.0`'s changelog) so that only the latest patch release's changelog shows. Do a quick review for formatting. Note: the `goreleaser` process should have detected if it's a pre-release version and, if so, checked the box at the bottom of the GitHub release page appropriately, but it's always worth double-checking. Verify that GitHub has built and pushed all the images (it takes a while): https://github.com/vmware-tanzu/velero/actions Verify that the images are on Docker Hub: https://hub.docker.com/r/velero/velero/tags Verify that the assets were published to the GitHub release Publish the release. Test the release By now, the Docker images should have been

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 These are the steps to update the Velero Homebrew version. If you don't already have one, create a Run `export HOMEBREWGITHUBAPITOKEN=yourtoken_here` on your command line to make sure that `brew` can work on GitHub on your behalf. Run `hack/release-tools/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. Update Windows Chocolatey version. From a Windows computer, follow the step-by-step instructions to To release plugins maintained by the Velero team, follow the . After the plugin images are built, be sure to update any that use these plugins. Update the CRDs under helm chart folder `crds` according to the current Velero GA version, and add the labels for the helm chart CRDs. For example: https://github.com/vmware-tanzu/helm-charts/pull/248. Bump the Chart version `version` on the `Chart.yaml`. Bump the Velero version `appVersion` on the `Chart.yaml` file and `tag` on the `values.yaml` file. Bump the plugin version on the `values.yaml` if needed. Update the upgrade instruction and related tag on the `README.md` file. 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 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 dont have to be publish all at once). Release blog post PR: Prepare a PR containing the release blog post. Read the 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 the blog post the same day as the release. Once you are finished doing the release, let the rest of the world know it's available by posting messages in the following places. GA Only: Merge the blog post PR. Velero's Twitter account. Maintainers are encouraged to help spread the word by posting or reposting on social media. Community Slack channel. 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