Skip to content

Release Process

Jump to bottom
Motiejus Jakštys edited this page Feb 22, 2024 · 23 revisions

Major, minor or patch releases?

hermetic_cc_toolchain being post-v1 means that it is used at large-scale in production, but not a specific backwards-compatibility promise.

The release criteria is as follows:

  • Major releases are for any backwards-incompatible changes.
  • Minor releases are for new features (workarounds for upstream count as features, not bug fixes).
  • Patch releases are for bug fixes in hermetic_cc_toolchain and upgrades of Zig SDK.

We do not promise to keep backwards compatibility, but we will warn about it by cutting a new major version. We do not intend to maintain past major versions unless there are exceptional circumstances.

Note that it is a good tone to cut a new release when Zig SDK is upgraded in hermetic_cc_toolchain, but by no means promised or required.

Cutting the release

1. Upgrade the Zig SDK

If Zig SDK has not been updated in a while (we try to update it at least every 2 months or so), here is how to do it:

  1. Run this and save the output:
wget https://ziglang.org/download/index.json
jq -r '.master | [.["aarch64-linux", "x86_64-linux", "aarch64-macos", "x86_64-macos", "aarch64-windows", "x86_64-windows"]] | .[].tarball' index.json
jq --indent 4 '.master | {
    "linux-aarch64": .["aarch64-linux"].shasum,
    "linux-x86_64": .["x86_64-linux"].shasum,
    "macos-aarch64": .["aarch64-macos"].shasum,
    "macos-x86_64": .["x86_64-macos"].shasum,
    "windows-aarch64": .["aarch64-windows"].shasum,
    "windows-x86_64": .["x86_64-windows"].shasum
}' index.json
  1. Create a mirror request to bazelbuild to mirror Zig SDK. This is necessary, because nightlies from ziglang.org/download expire in about 3 months. Use output from the previous step to fill the request.
  2. Edit VERSION, HOST_PLATFORM_SHA256 in toolchain/private/zig_sdk.bzl. Use output from the previous step.
  3. Run all the tests (or push to a branch, so CI can do it for you).
  4. Test your project with the new SDK. If you work at Uber, test the world with the new SDK.
  5. Once mirroring is complete, submit the PR to change the version and the hashes in hermetic_cc_toolchain. Note the test you have done in the PR.
  6. Proceed with cutting the release below.

2. Run the releaser tool

bazel run //tools/releaser -- -tag v<version>

Releaser will:

  1. Create an archive hermetic_cc_toolchain-v<version>.tar.gz in the top level of the repository.
  2. Update the version in MODULE.bazel, README.md and examples
  3. If there is no tag named v<version>, commit the change and tag the commit
  4. Suggest a "release boilerplate". Save the output of the command somewhere.

3. Push the tag

git push upstream v<version>

This assumes that upstream points to the main repo under github.com/uber. We need to push the tag there because we will create a release out of the main repo.

4. Create a new release in Github

Before you start, make sure you have forked Bazel Central Registry to your personal Github account and installed Publish to BCR app to the forked repo. This is needed to automatically publish the new release to BCR.

  1. Open https://github.com/uber/hermetic_cc_toolchain/releases/new
  2. Select the tag you have just pushed.
  3. Populate the release title and notes, upload the release archive hermetic_cc_toolchain-v<version>.tar.gz that was created in step 2. Note that, especially for major releases, you must explain what the backwards-incompatible changes are. Mark a pre-release version.

After the release is published, a pull request will be created from your BCR fork. If there is any issues in the CI, follow the process of fixing existing release below. If CI finishes successfully, it will be merged by "BCR maintainers".

5. Create a pull request

  1. Create a branch out of the newly-created tag to a remote branch from which you can create a pull request:

    git checkout -b release-v<version> v<version>
git push origin release-v<version>

  2. Create a pull request from that branch.

  3. If there are issues in CI, follow the process of fixing existing release below.

  4. When merging, you must include the merge commit. If you squash or rebase instead, the tag will be pointing to the wrong SHA in the branch (or conversely, the SHA in the branch will be a duplicate commit with the tag). This is too easy to screw up, but possible to do right.

6. Mirror the release archive

  1. Create a mirror request to mirror the new release archive to Bazel mirror at https://github.com/bazelbuild/bazel/issues/new/choose.
  2. After the mirror request has been fulfilled, change the new release: unmark pre-release and mark "set as latest release".

Fixing existing release

If there are issues in the CI of either BCR or hermetic_cc_toolchain during the release process, you need to fix the issue, possibly open a pull request for the fix and restart the release process. But since you are fixing existing release instead of creating a new one, there are a few changes to the process above:

  1. because the releaser created a commit on top of local main branch, you need to delete that commit by running git reset --hard upstream/main
  2. delete the tag created previously, so the releaser will tag the version on the latest HEAD: git tag -d v<version>
  3. upload the release archive hermetic_cc_toolchain-v<version>.tar.gz to the existing release instead of creating a new one
  4. manually create a pull request to BCR, because Publish to BCR will not create another one with the new archive.
Clone this wiki locally