We generally avoid making backwards-incompatible changes. We have several years of experience with supporting a huge code base that is concurrently worked on by thousands of engineers every day, and have successfully made significant changes to the core as well as to the rules without missing a beat. We run hundreds of thousands of tests at Google before every single release to ensure that it stays that way.
That said, we occasionally have to make incompatible changes in order to fix bugs, to make further improvements to the system, such as improving performance or usability, or to lock down APIs that are known to be brittle.
This document gives an overview of features that are widely used and that we consider stable. By stable, we mean that the changes we make will be backwards compatible, or that we will provide a migration path.
It also covers features that are unstable. Either they are not yet widely used, or we are already planning to change them significantly, possibly in ways that are not backwards compatible.
We cannot cover everything that might change, but you can reasonably expect that we provide advance notice on the mailing list before a major change happens. We're also happy to provide more details, just ask on bazel-discuss.
All undocumented features (attributes, rules, “Make” variables, and flags) are subject to change at any time without prior notice. Features that are documented but marked experimental are also subject to change at any time without prior notice.
The Skylark macro and rules language (anything you write in a .bzl file) is still subject to change. We are in the process of migrating Google to Skylark, and expect the macro language to stabilize as part of that process. The rules language is still somewhat experimental.
Help keep us honest: report bugs and regressions in the GitHub bugtracker. We will make an effort to triage all reported issues within 2 business days.
We regularly publish binary releases of Bazel. To that end, we announce release candidates on bazel-discuss; these are binaries that have passed all of our unit tests. Over the next few days, we regression test all applicable build targets at Google. 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.
If no regressions are discovered, we officially release the candidate after a week. However, regressions can delay the release of a release candidate. If regressions are found, we apply corresponding cherry-picks to the release candidate to fix those regressions. If no further regressions are found for two business days, but not before a week has elapsed since the first release candidate, we release it.
Version 0.1 is our first release marking the start of our beta phase. Until version 1.0.0, we increase the MINOR version every time we reach a new milestone.
Version 1.0.0 marks the end of our beta phase; afterwards, we will label each release with a version number of the form MAJOR.MINOR.PATCH according to the semantic version 2.0.0 document.
We are planning a number of changes to the APIs between the core of Bazel and the built-in rules, in order to make it easier for us to develop openly. This has the added benefit of also making it easier for users to maintain their own rules (if written in Java instead of Skylark), if they don't want to or cannot check this code into our repository. However, it also means our internal API is not stable yet. In the long term, we want to move to Skylark wholesale, so we encourage contributors to use Skylark instead of Java when writing new rules. Rewriting all of our built-in rules is going to be a lengthy process however.
We expect the following rules and features to be stable. They are widely used within Google, so our internal testing should ensure that there are no major breakages.
These rules and features have known limitations that we will likely address in future releases.