Update Bazel's release model Based on https://docs.google.com/document/d/1e34nIWO51ybEIr9N7WoR-bMVZgRPD_WKGky-L7_NKho/edit# PiperOrigin-RevId: 532074225 Change-Id: Ieebf75a4c8e149b20c9b054ea9274bd7496c26cf
diff --git a/site/en/_book.yaml b/site/en/_book.yaml index 3ad3764..bc2ef75 100644 --- a/site/en/_book.yaml +++ b/site/en/_book.yaml
@@ -95,12 +95,12 @@ other: - name: Releases contents: - - title: Overview + - title: Release model path: /release/ - - title: Release versioning - path: /release/versioning - title: Backward compatibility path: /release/backward-compatibility + - title: Rule compatibility + path: /release/rule-compatibility - name: Basics contents: - heading: Getting started with BUILD files
diff --git a/site/en/docs/images/roadmap.png b/site/en/docs/images/roadmap.png deleted file mode 100644 index 9ca1466..0000000 --- a/site/en/docs/images/roadmap.png +++ /dev/null Binary files differ
diff --git a/site/en/release/backward-compatibility.md b/site/en/release/backward-compatibility.md index cb9034d..5fb54fb 100644 --- a/site/en/release/backward-compatibility.md +++ b/site/en/release/backward-compatibility.md
@@ -5,30 +5,33 @@ {% include "_buttons.html" %} -This page provides information on how to handle backward compatibility, +This page provides information about how to handle backward compatibility, including migrating from one release to another and how to communicate incompatible changes. -Bazel is evolving. Minor versions released as part of an -[LTS major version](/release/versioning#lts-releases) are fully backward-compatible. -Changes between major LTS releases may contain incompatible changes that require -some migration effort. For more information on how the Bazel release cadence -works, see -[Announcing Bazel Long Term Support (LTS) releases](https://blog.bazel.build/2020/11/10/long-term-support-release.html). +Bazel is evolving. Minor versions released as part of an [LTS major +version](/release#bazel-versioning) are fully backward-compatible. New major LTS +releases may contain incompatible changes that require some migration effort. +For more information about Bazel's release model, please check out the [Release +Model](/release) page. ## Summary {:#summary} -1. It is recommended to use `--incompatible_*` flags for breaking changes. -1. For every `--incompatible_*` flag, a GitHub issue explains - the change in behavior and aims to provide a migration recipe. -1. APIs and behavior guarded by an `--experimental_*` flag can change at any time. -1. Never run production builds with `--experimental_*` or `--incompatible_*` flags. +1. It is recommended to use `--incompatible_*` flags for breaking changes. +1. For every `--incompatible_*` flag, a GitHub issue explains the change in + behavior and aims to provide a migration recipe. +1. Incompatible flags are recommended to be back-ported to the latest LTS + release without enabling the flag by default. +1. APIs and behavior guarded by an `--experimental_*` flag can change at any + time. +1. Never run production builds with `--experimental_*` or `--incompatible_*` + flags. ## How to follow this policy {:#policy} -* [For Bazel users - how to update Bazel](/install/bazelisk) -* [For contributors - best practices for incompatible changes](/contribute/breaking-changes) -* [For release managers - how to update issue labels and release](https://github.com/bazelbuild/continuous-integration/tree/master/docs/release-playbook.%6D%64){: .external} +* [For Bazel users - how to update Bazel](/install/bazelisk) +* [For contributors - best practices for incompatible changes](/contribute/breaking-changes) +* [For release managers - how to update issue labels and release](https://github.com/bazelbuild/continuous-integration/tree/master/docs/release-playbook.%6D%64){: .external} ## What is stable functionality? {:#stable-functionality} @@ -37,30 +40,38 @@ This includes: -* Starlark language and APIs -* Rules bundled with Bazel -* Bazel APIs such as Remote Execution APIs or Build Event Protocol -* Flags and their semantics +* Starlark language and APIs +* Rules bundled with Bazel +* Bazel APIs such as Remote Execution APIs or Build Event Protocol +* Flags and their semantics ## Incompatible changes and migration recipes {:#incompatible-changes} For every incompatible change in a new release, the Bazel team aims to provide a -_migration recipe_ that helps you update your code -(`BUILD` and `.bzl` files, as well as any Bazel usage in scripts, -usage of Bazel API, and so on). +_migration recipe_ that helps you update your code (`BUILD` and `.bzl` files, as +well as any Bazel usage in scripts, usage of Bazel API, and so on). Incompatible changes should have an associated `--incompatible_*` flag and a corresponding GitHub issue. +The incompatible flag and relevant changes are recommended to be back-ported to +the latest LTS release without enabling the flag by default. This allows users +to migrate for the incompatible changes before the next LTS release is +available. + ## Communicating incompatible changes {:#communicating-incompatible-changes} The primary source of information about incompatible changes are GitHub issues -marked with an ["incompatible-change" label](https://github.com/bazelbuild/bazel/issues?q=label%3Aincompatible-change){: .external}. +marked with an ["incompatible-change" +label](https://github.com/bazelbuild/bazel/issues?q=label%3Aincompatible-change){: .external}. For every incompatible change, the issue specifies the following: -* Name of the flag controlling the incompatible change -* Description of the changed functionality -* Migration recipe +* Name of the flag controlling the incompatible change +* Description of the changed functionality +* Migration recipe -When an incompatible change is ready for migration with Bazel at HEAD (therefore, also with the next Bazel rolling release), it should be marked with the `migration-ready` label. The incompatible change issue is closed when the incompatible flag is flipped at HEAD. +When an incompatible change is ready for migration with Bazel at HEAD +(therefore, also with the next Bazel rolling release), it should be marked with +the `migration-ready` label. The incompatible change issue is closed when the +incompatible flag is flipped at HEAD. \ No newline at end of file
diff --git a/site/en/release/index.md b/site/en/release/index.md index 22d02bd..c3cd49e 100644 --- a/site/en/release/index.md +++ b/site/en/release/index.md
@@ -1,64 +1,178 @@ Project: /_project.yaml Book: /_book.yaml -# Release Policy +# Release Model {% dynamic setvar source_file "site/en/release/index.md" %} {% include "_buttons.html" %} -Bazel maintains a -[Long Term Support (LTS)](/release/versioning) -release model, where a major version is released every nine months and minor -versions are released monthly. This page covers the Bazel release policy, -including the release candidates, timelines, announcements, and testing. +As announced in [the original blog +post](https://blog.bazel.build/2020/11/10/long-term-support-release.html), Bazel +4.0 and higher versions provides support for two release tracks: rolling +releases and long term support (LTS) releases. This page covers the latest +information about Bazel's release model. -Bazel releases can be found on -[GitHub](https://github.com/bazelbuild/bazel/releases){: .external}. +## Release versioning {:#bazel-versioning} -## Release candidates {:#release-candidates} +Bazel uses a _major.minor.patch_ [Semantic +Versioning](https://semver.org/){: .external} scheme. -A release candidate for a new version of Bazel is usually created at the -beginning of every month. The work is tracked by a -[release bug on GitHub](https://github.com/bazelbuild/bazel/issues?q=is%3Aissue+is%3Aopen+label%3Arelease){: .external} -indicating a target release date, and is assigned to the current Release manager. -Release candidates should pass all Bazel unit tests, and show no unwanted -regression in the projects tested on [Buildkite](https://buildkite.com/bazel){: .external}. +* A _major release_ contains features that are not backward compatible with + the previous release. Each major Bazel version is an LTS release. +* A _minor release_ contains backward-compatible bug fixes and features + back-ported from the main branch. +* A _patch release_ contains critical bug fixes. -Release candidates are announced on -[bazel-discuss](https://groups.google.com/g/bazel-discuss){: .external}. -Over the next days, the Bazel team monitors community bug reports for any -regressions in the candidates. +Additionally, pre-release versions are indicated by appending a hyphen and a +date suffix to the next major version number. -## Releasing {:#releasing} +For example, a new release of each type would result in these version numbers: -If no regressions are discovered, the candidate is officially released after -one week. However, regressions can delay the release of a release candidate. If -regressions are found, the Bazel team applies corresponding cherry-picks to the -release candidate to fix those regressions. If no further regressions are found -for two consecutive business days beginning after one week since the first -release candidate, the candidate is released. +* Major: 6.0.0 +* Minor: 6.1.0 +* Patch: 6.1.2 +* Pre-release: 7.0.0-pre.20230502.1 -New features are not cherry-picked into a release candidate after it is cut. -Moreover, if a new feature is buggy, the feature may be rolled back from a -release candidate. Only bugs that have the potential to highly impact or break -the release build are fixed in a release candidate after it is cut. +## Support stages {:#support-stages} -A release is only released on a day where the next day is a business day. +For each major Bazel version, there are four support stages: -If a critical issue is found in the latest release, the Bazel team creates a -patch release by applying the fix to the release. Because this patch updates an -existing release instead of creating a new one, the patch release candidate can -be released after two business days. +* **Rolling**: This major version is still in pre-release, the Bazel team + publishes rolling releases from HEAD. +* **Active**: This major version is the current active LTS release. The Bazel + team backports important features and bug fixes into its minor releases. +* **Maintenance**: This major version is an old LTS release in maintenance + mode. The Bazel team only promises to backport critical bug fixes for + security issues and OS-compatibility issues into this LTS release. +* **Deprecated**: The Bazel team no longer provides support for this major + version, all users should migrate to newer Bazel LTS releases. -## Testing {:#testing} +## Release cadence {:#release-cadence} -A nightly build of all projects running on -[ci.bazel.build](https://github.com/bazelbuild/continuous-integration/blob/master/buildkite/README.md){: .external} is run, using Bazel -binaries built at head, and release binaries. Projects going to be impacted by a -breaking change are notified. +Bazel regularly publish releases for two release tracks. -When a release candidate is issued, other Google projects like -[TensorFlow](https://tensorflow.org){: .external} are tested on their complete -test suite using the release candidate binaries. If you have a critical project -using Bazel, we recommend that you establish an automated testing process that -tracks the current release candidate, and report any regressions. +### Rolling releases {:#rolling-releases} + +* Rolling releases are coordinated with Google Blaze release and are released + from HEAD around every two weeks. It is a preview of the next Bazel LTS + release. +* Rolling releases can ship incompatible changes. Incompatible flags are + recommended for major breaking changes, rolling out incompatible changes + should follow our [backward compatibility + policy](/release/backward-compatibility). + +### LTS releases {:#lts-releases} + +* _Major release_: A new LTS release is expected to be cut from HEAD roughly + every + 12 months. Once a new LTS release is out, it immediately enters the Active + stage, and the previous LTS release enters the Maintenance stage. +* _Minor release_: New minor verions on the Active LTS track are expected to + be released once every 2 months. +* _Patch release_: New patch versions for LTS releases in Active and + Maintenance stages are expected to be released on demand for critical bug + fixes. +* A Bazel LTS release enters the Deprecated stage after being in the + Maintenance stage for 2 years. + +For planned releases, please check our [release +issues](https://github.com/bazelbuild/bazel/issues?q=is%3Aopen+is%3Aissue+label%3Arelease){: .external} +on Github. + +## Support matrix {:#support-matrix} + +| LTS release | Support stage | Latest version | End of support | +| ----------- | ------------- | -------------- | -------------- | +| Bazel 7 | Rolling| [Check GitHub release page](https://github.com/bazelbuild/bazel/releases){: .external} | N/A | +| Bazel 6 | Active | [6.2.0](https://github.com/bazelbuild/bazel/releases/tag/6.2.0){: .external} | Dec 2025 | +| Bazel 5 | Maintenance | [5.4.1](https://github.com/bazelbuild/bazel/releases/tag/5.4.1){: .external} | Jan 2025 | +| Bazel 4 | Maintenance | [4.2.4](https://github.com/bazelbuild/bazel/releases/tag/4.2.4){: .external} | Jan 2024 | + +All Bazel releases can be found on the [release +page](https://github.com/bazelbuild/bazel/releases){: .external} on GitHub. + +Note: Bazel version older than Bazel 4 are no longer supported, Bazel users are +recommended to upgrade to the latest LTS release or use rolling releases if you +want to keep up with the latest changes at HEAD. + +## Release procedure & policies {:#release-procedure-policies} + +For rolling releases, the process is straightforward: about every two weeks, a +new release is created, aligning with the same baseline as the Google internal +Blaze release. Due to the rapid release schedule, we don't backport any changes +to rolling releases. + +For LTS releases, the procedure and policies below are followed: + +1. Determine a baseline commit for the release. + * For a new major LTS release, the baseline commit is the HEAD of the main + branch. + * For a minor or patch release, the baseline commit is the HEAD of the + current latest version of the same LTS release. +1. Create a release branch in the name of `release-<version>` from the baseline + commit. +1. Backport changes via PRs to the release branch. + * The community can suggest certain commits to be back-ported by replying + "`@bazel-io flag`" on relevant GitHub issues or PRs to mark them as potential + release blockers, the Bazel team triages them and decide whether to + back-port the commits. + * Only backward-compatible commits on the main branch can be back-ported, + additional minor changes to resolve merge conflicts are acceptable. +1. Identify release blockers and fix issues found on the release branch. + * The release branch is tested with the same test suite in + [postsubmit](https://buildkite.com/bazel/bazel-bazel){: .external} and + [downstream test pipeline] + (https://buildkite.com/bazel/bazel-at-head-plus-downstream){: .external} + on Bazel CI. The Bazel team monitors testing results of the release + branch and fixes any regressions found. +1. Create a new release candidate from the release branch when all known + release blockers are resolved. + * The release candidate is announced on + [bazel-discuss](https://groups.google.com/g/bazel-discuss){: .external}, + the Bazel team monitors community bug reports for the candidate. + * If new release blockers are identified, go back to the last step and + create a new release candidate after resolving all the issues. + * New features are not allowed to be added to the release branch after the + first release candidate is created. +1. Push the release candidate as the official release if no further release + blockers are found + * For patch releases, push the release at least two business days after + the last release candidate is out. + * For major and minor releases, push the release two business days after + the last release candidate is out, but not earlier than one week after + the first release candidate is out. + * The release is only pushed on a day where the next day is a business + day. + * The release is announced on + [bazel-discuss](https://groups.google.com/g/bazel-discuss){: .external}, + the Bazel team monitors and addresses community bug reports for the new + release. + +## Report regressions {:#report-regressions} + +If a user finds a regression in a new Bazel release, release candidate or even +Bazel at HEAD, please file a bug on +[GitHub](https://github.com/bazelbuild/bazel/issues){: .external}. You can use +Bazelisk to bisect the culprit commit and include this information in the bug +report. + +For example, if your build succeeds with Bazel 6.1.0 but fails with the second +release candidate of 6.2.0, you can do bisect via + +```bash +bazelisk --bisect=6.1.0..release-6.2.0rc2 build //foo:bar +``` + +You can set `BAZELISK_SHUTDOWN` or `BAZELISK_CLEAN` environment variable to run +corresponding bazel commands to reset the build state if it's needed to +reproduce the issue. For more details, check out documentation about Bazelisk +[bisect feature] (https://github.com/bazelbuild/bazelisk#--bisect){: .external}. + +Remember to upgrade Bazelisk to the latest version to use the bisect +feature. + +## Rule compatibility {:#rule-compatibility} + +If you are a rule authors and want to maintain compatibility with different +Bazel versions, please check out the [Rule +Compatibility](/release/rule-compatibility) page. \ No newline at end of file
diff --git a/site/en/release/rule-compatibility.md b/site/en/release/rule-compatibility.md new file mode 100644 index 0000000..56f9c43 --- /dev/null +++ b/site/en/release/rule-compatibility.md
@@ -0,0 +1,91 @@ +Project: /_project.yaml +Book: /_book.yaml + +# Rule Compatibility + +{% include "_buttons.html" %} + +Bazel Starlark rules can break compatibility with Bazel LTS releases in the +following two scenarios: + +1. The rule breaks compatibility with future LTS releases because a feature it + depends on is removed from Bazel at HEAD. +1. The rule breaks compatibility with the current or older LTS releases because + a feature it depends on is only available in newer Bazel LTS releases. + +Meanwhile, the rule itself can ship incompatible changes for their users as +well. When combined with breaking changes in Bazel, upgrading the rule version +and Bazel version can often be a source of frustration for Bazel users. This +page covers how rules authors should maintain rule compatibility with Bazel to +make it easier for users to upgrade Bazel and rules. + +## Manageable migration process {:#manageable-migration-process} + +While it's obviously not feasible to guarantee compatibility between every +version of Bazel and every version of the rule, our aim is to ensure that the +migration process remains manageable for Bazel users. A manageable migration +process is defined as a process where **users are not forced to upgrade the +rule's major version and Bazel's major version simultaneously**, thereby +allowing users to handle incompatible changes from one source at a time. + +For example, with the following compatibility matrix: + +* Migrating from rules_foo 1.x + Bazel 4.x to rules_foo 2.x + Bazel 5.x is not + considered manageable, as the users need to upgrade the major version of + rules_foo and Bazel at the same time. +* Migrating from rules_foo 2.x + Bazel 5.x to rules_foo 3.x + Bazel 6.x is + considered manageable, as the users can first upgrade rules_foo from 2.x to + 3.x without changing the major Bazel version, then upgrade Bazel from 5.x to + 6.x. + +| | rules_foo 1.x | rules_foo 2.x | rules_foo 3.x | HEAD | +| --- | --- | --- | --- | --- | +| Bazel 4.x | ✅ | ❌ | ❌ | ❌ | +| Bazel 5.x | ❌ | ✅ | ✅ | ❌ | +| Bazel 6.x | ❌ | ❌ | ✅ | ✅ | +| HEAD | ❌ | ❌ | ❌ | ✅ | + +❌: No version of the major rule version is compatible with the Bazel LTS +release. + +✅: At least one version of the rule is compatible with the latest version of the +Bazel LTS release. + +## Best practices {:#best-practices} + +As Bazel rules authors, you can ensure a manageable migration process for users +by following these best practices: + +1. The rule should follow [Semantic + Versioning](https://semver.org/){: .external}: minor versions of the same + major version are backward compatible. +1. The rule at HEAD should be compatible with the latest Bazel LTS release. +1. The rule at HEAD should be compatible with Bazel at HEAD. To achieve this, + you can + * Set up your own CI testing with Bazel at HEAD + * Add your project to [Bazel downstream + testing](https://github.com/bazelbuild/continuous-integration/blob/master/docs/downstream-testing.md){: .external}; + the Bazel team files issues to your project if breaking changes in Bazel + affect your project, and you must follow our [downstream project + policies](https://github.com/bazelbuild/continuous-integration/blob/master/docs/downstream-testing.md#downstream-project-policies){: .external} + to address issues timely. +1. The latest major version of the rule must be compatible with the latest + Bazel LTS release. +1. A new major version of the rule should be compatible with the last Bazel LTS + release supported by the previous major version of the rule. + +Achieving 2. and 3. is the most important task since it allows achieving 4. and +5. naturally. + +To make it easier to keep compatibility with both Bazel at HEAD and the latest +Bazel LTS release, rules authors can: + +* Request backward-compatible features to be back-ported to the latest LTS + release, check out [release process](/release#release-procedure-policies) + for more details. +* Use [bazel_features](https://github.com/bazel-contrib/bazel_features){: .external} + to do Bazel feature detection. + +In general, with the recommended approaches, rules should be able to migrate for +Bazel incompatible changes and make use of new Bazel features at HEAD without +dropping compatibility with the latest Bazel LTS release. \ No newline at end of file
diff --git a/site/en/release/versioning.md b/site/en/release/versioning.md deleted file mode 100644 index e387ecb..0000000 --- a/site/en/release/versioning.md +++ /dev/null
@@ -1,96 +0,0 @@ -Project: /_project.yaml -Book: /_book.yaml - -# Release Versioning - -{% include "_buttons.html" %} - -Bazel 4.0 and higher provides support for two release tracks: long term support -(LTS) releases and rolling releases. This page covers versioning in Bazel, the -types of releases, and the benefits of those releases for Bazel users and -contributors. - -## Understanding versioning on Bazel {:#bazel-versioning} - -Bazel uses a _major.minor.patch_ semantic versioning scheme. - -* A _major release_ contains features that are not backward compatible with the - previous release. -* A _minor release_ contains new backward-compatible features. -* A _patch release_ contains minor changes and bug fixes. - -Using version 3.5.1 as an example, a new release of each type would result in -these version numbers: - -* Major: 4.0 -* Minor: 3.6 -* Patch: 3.5.2 - -## Bazel's release cycle {:#release-cycle} - -Bazel continually publishes rolling releases. Every major version is an LTS -release. You can choose to follow either release cadence - updating from one -LTS release to the next, or updating with each minor version release. - -The image shows both rolling and LTS releases, and the expected support for -each. - - - -**Figure 1.** Rolling and LTS releases. - -## Release branches {:#release-branches} - -Each major version becomes a separate development branch on release. You can -receive fixes to critical bugs on that branch without having to update to the -Bazel release at head. Additional features on your major version branch become -minor releases and the highest version on the branch is the supported version. - -Each Bazel release is paired with a list of recommended rule versions that work -together and there is strict backwards compatibility within each branch. - -## LTS releases {:#lts-releases} - -An LTS release is a major version (such as, 4.0) that is supported for 3 years -after its release. -A major version is released approximately every nine months. - -Ongoing development on a release branch results in minor versions. - -You can choose to pin your project to a major release and update to a newer -version in your own time. This gives you time to preview upcoming changes and -adapt to them in advance. - -## Rolling releases {:#rolling-releases} - -Rolling releases are periodically cut from Bazel's main branch. -This release cadence involves a continuous delivery of preview releases of the -next major Bazel version, which are in sync with Google’s internal Blaze -releases. - -Note that a new rolling release can contain breaking changes that are -incompatible with previous releases. - -Rolling releases are tested on Bazel's test suite on Bazel CI and -Google’s internal test suite. Incompatible flags may be -used to ease the burden of migrating to new functionality, but default behaviors -may change with any rolling release. (You can also use rolling releases to -preview the next LTS version. For example, `5.0.0-pre.20210604.6` is based on a -candidate cut on 2021-06-04 and represents a milestone towards the 5.0 LTS -release.) - -You can download the latest rolling release from -[GitHub](https://github.com/bazelbuild/bazel/releases){: .external}. -Alternatively, you can set up -[Bazelisk v1.9.0](https://github.com/bazelbuild/bazelisk/releases/tag/v1.9.0){: .external} -(or later) to use a specific version name or the -“rolling” identifier, which uses the most recent rolling release. For more -details, see the -[Bazelisk documentation](https://github.com/bazelbuild/bazelisk#how-does-bazelisk-know-which-bazel-version-to-run){: .external}. - -## Updating versions {:#updating-versions} - -* For more information on updating your Bazel version, see - [Updating Bazel](/install/bazelisk). -* For more information on contributing updates to new Bazel releases, see - [Contributing to Bazel](/contribute).
