The list of design documents is published on the Bazel Proposals Repository.
It’s possible that designs change as they are implemented in practice. The published design documents capture the initial design, and not the ongoing changes as designs are implemented.
Always go to the documentation for descriptions of current Bazel functionality.
If you’re planning to add, change, or remove a user-facing feature, or make a significant architectural change to Bazel, you must write a design document and have it reviewed before you can submit the change. See What is a significant change? for details.
Implementation can begin before the proposal is accepted, for example as a proof-of-concept or an experimentation. However, you cannot submit the change before the review is complete.
All design documents must have a header that includes:
Proposals that have a user-visible impact must have a section documenting the impact on backward compatibility (and a rollout plan if needed).
The author creates a Pull Request (PR) to add the document to the design index. If the proposal is a Markdown file, the file is added in the same PR. Otherwise, the PR only adds a link.
When possible, the author chooses a lead reviewer. Other reviewers are cc’ed. If the author didn’t choose a lead reviewer, the Bazel sheriff will assign one, like for any other PR.
Once the PR is sent, the reviewers can make some preliminary comments during the code review. For example, the lead reviewer can suggest extra reviewers, or point out missing information. The lead reviewer approves the PR when they believe the review process can start. It doesn’t mean the proposal is perfect or will be approved; it means that the proposal contains enough information to start the discussion.
Once the PR is submitted, the author sends an announcement to bazel-dev.
Other groups may be cc’ed (e.g. bazel-discuss, to get feedback from Bazel end-users).
Anyone interested can chime in and comment on the proposal. The author should try to answer questions, clarify the proposal, and address the concerns.
Discussion should happen on the announcement thread. If the document is a Google Doc, comments may be used instead (but note that anonymous comments are allowed).
When the author believes the iteration round is complete, they send a new PR to update the status. The PR must be sent to the same lead reviewer and cc the other reviewers.
The lead reviewer approves the PR to officially accept the proposal. It is the lead reviewer’s responsibility to ensure that other reviewers agree with the decision.
There must be at least 1 week between the first announcement and the approval of a proposal. This ensures that users had enough time to read the document and share their concerns.
Both are accepted. The author can decide what works best for them.
Google Docs can be more effective for brainstorming, collaborative editing, and quick iteration. Suggested edits are also very valuable.
Markdown files have some other benefits, including:
It is also possible to first iterate on a Google Doc, and then convert it to Markdown for posterity.
Create a world-readable document on Google Doc. To make it world-readable, click on “Share”, “Advanced”, then “Change…”, and choose “On - Anyone with the link”. You may allow comments on the document. If you do so, anyone will be able to comment anonymously, even without a Google account.
We recommend that you use this template for new documents. It will help you structure the document and create a visual consistency with other Bazel related documents. To do that, click on “Make a copy” under the “File” menu.
Send a PR to update an existing document. Significant changes should be reviewed by the document reviewers. Trivial changes (e.g. typos, formatting) can be approved by anyone.
The lead reviewer is a domain expert. Lead reviewers must be:
If you get a design review request, please make sure it followed this process. Do not approve designs affecting Bazel if they are not in the design index.
You’re ultimately responsible for making a go/no-go decision on implementation of a pending design. If you’re not able to do this, you should identify a suitable delegate (reassign the PR to the delegate), or reassign the bug to a Blaze manager for further disposition.
There are no hard and fast criteria, but here are some examples:
When a proposal adds, removes, or modifies any function or object available in BUILD, WORKSPACE, or bzl files, Skylark team has to be in the reviewers list.