Release process

Minor releases (0.X.0)

• Update dependencies to their latest release.
• Decide on a new version number. The first digit should be zero until we decide we're stable enough to be 1.0. The API has been stable for a while, but we should identify any API tech debt that needs to be deleted before committing to long-term stability. The second digit should be incremented (and the third digit set to 0) for releases from master with new features. The third digit should be incremented for bugfix releases (generally these are cherry-picks on top of an older release).
• In go/def.bzl, commit a change setting RULES_GO_VERSION to the new version. For minor releases, this change should be on the master branch.
• Write release notes as a Markdown file. Don't include the WORKSPACE boilerplate section for now.
• Run the releaser tool:

bazel run //go/tools/releaser -- prepare -rnotes=$rnotes -version=$version -githubtoken=$githubtoken

where $rnotes is the release notes file, $version is the version to prepare (of the form v1.2.4), and $githubtoken is either a GitHub personal access token or the name of a file containing one.

This command does the following.

• Creates the release branch if it doesn't exist locally. Release branches have names like "release-X.Y" where X and Y are the major and minor version numbers.
• Checks that RULES_GO_VERSION is set in go/def.bzl on the local release branch for the minor version being released. RULES_GO_VERSION must be a semantic version without the "v" prefix that Go uses, like "1.2.4". It must match the -version flag, which does require the "v" prefix.
• Creates an archive zip file from the tip of the local release branch.
• Creates or updates a draft GitHub release with the given release notes. http_archive boilerplate is generated and appended to the release notes.
• Uploads and attaches the release archive to the GitHub release.
• Uploads the release archive to mirror.bazel.build. If the file already exists, it may be manually removed with gsutil rm gs://bazel-mirror/<github-url> or manually updated with gsutil cp <file> gs://bazel-mirror/<github-url>. This step requires write access to bazel-mirror. It may be skipped by setting -mirror=false.

After these steps are completed successfully, the releaser tool should prompt you to check that CI passes on the release branch, then review and publish the GitHub release.

After the release is complete:

• Add an announcement to the top of README.rst and update WORKSPACE boilerplate.
• Update Gazelle to use the new version.

Patch releases (0.X.Y)

The procedure for minor releases is mostly the same as major releases, with a few important differences.

• Minor releases are tagged from a release branch, not master. The release branch should have a name like release-0.10 and should start at a major release tag (like v0.10.0).
  • Commits are cherry-picked to this branch. Review is only needed if there are significant differences with backporting. The branch may be pushed to the origin repo manually.
  • BuildKite will automatically run CI on pushes to branches in the main repo. Confirm that tests pass at https://buildkite.com/bazel/rules-go-golang before proceeding.
• Release notes should contain a list of bug fixes (not normally included in major releases) and WORKSPACE boilerplate.
• The boilerplate code in README.rst only needs to be updated for the latest release branch. An announcement should be added to README.rst in any case.
• README.rst is updated on the master branch, not on the release branch.