Guide for Bazel Maintainers
Table of Contents
This is a guide for the maintainers of the Bazel open source project.
If you are looking to contribute to Bazel, please read Contributing to
The objectives of this document are to:
- Serve as the maintainers’ source of truth for the project’s contribution
- Set expectations between the community contributors and the project
Bazel’s core group of contributors has dedicated subteams to
manage aspects of the open source project. These are:
- User Onboarding: Improve the experience for new Bazel users, and help them
- Release Process: Manage Bazel’s release process.
- Green Team: Grow a healthy ecosystem of rules and tools.
- Developer Experience: Encourage external contributions, make our
development workflow more open, and shift the team towards GitHub-first
Read the Green team’s guide to Bazel’s CI infrastructure on the
Lifecycle of an Issue
- A user creates an issue using the Issue
and it enters the pool of unreviewed open
- A member on the Developer Experience (DevEx) subteam rotation reviews the
- If the issue is not a bug or a feature request, the DevEx member
will close the issue and redirect the user to
higher visibility on the question.
- If the issue is vague or has missing information, the DevEx member will
assign the issue back to the user to request for more information before
continuing. This usually occurs when the user does not follow the Issue
- After reviewing the issue, the DevEx member decides if the issue requires
immediate attention. If it does, they will assign the P0
priority label and an owner from the list of team leads.
- The DevEx member assigns the
untriaged label and exactly one team
label for routing.
- The DevEx member also assigns the
feature request label according
to the type of the issue.
At this stage, the issue enters the pool of untriaged open
Each Bazel subteam will triage all issues under labels they own, preferably on a
weekly basis. The subteam will review and evaluate the issue and provide a
resolution, if possible. If you are a owner of a team label, see this section
When an issue is resolved, it can be closed.
Lifecycle of a Pull Request
- A user creates a pull request.
- A DevEx member assigns one team label and the team’s
technical lead (TL) for routing.
- The TL may optionally assign someone else to review the PR.
- The assigned reviewer reviews the PR and works with the author until it is
approved or dropped.
- If approved, the reviewer imports the PR’s commit(s) into Google’s
internal version control system for further tests. As Bazel is the same build
system used internally at Google, we need to test all PR commits against the
internal test suite. This is the reason why we do not merge PRs directly.
- If the imported commit passes all internal tests, the commit will be squashed
and exported back out to GitHub.
- When the commit merges into master, GitHub automatically closes the PR.
When someone opens a new issue or pull request (PR) on Bazel’s GitHub
repository, it needs to be routed to the appropriate owners for triaging.
For a large project like Bazel, routing issues and PRs in a timely manner has
many benefits, including:
- Acknowledging the contributor’s time and effort to open an issue or PR.
- Maximizing the visibility of the issue or PR towards domain experts.
- Reducing the maintainers’ toil on sifting through the large volume of issues
When an issue or PR is routed to the correct owner, the owner can address and
prioritize the issue accordingly.
The Developer Experience (DevEx) subteam handles the initial routing of issues
and PRs on weekly rotation basis. The subteam can be reached on GitHub using the
Routed issues must have:
team label, e.g.
- either the
untriaged label OR one priority label (
p4), but not both.
The exceptions to this are issues for tracking releases and incompatible changes.
See the list of issues to be routed
My team owns a label. What should I do?
Subteams need to triage all issues in the labels they own,
preferable on a weekly basis.
- Filter the list of issues by your team label and the
- Review the issue.
- Identify a priority level and assign the label.
- The issue may have already been prioritized by the DevEx subteam if it’s a
P0. Re-prioritize if needed.
- Remove the
Note that you need to be in the bazelbuild
organization to be able to add or remove labels.
- Filter the list of pull requests by your team label.
- Review open pull requests.
- Optional: If you are assigned for the review but is not the right fit
for it, re-assign the appropriate reviewer to perform a code review.
- Work with the pull request creator to complete a code review.
- Approve the PR.
- Ensure that all tests pass.
- Import the patch to the internal version control system and run the internal
- Submit the internal patch. If the patch submits and exports successfully, the
PR will be closed automatically by GitHub.
The following definitions for priority will be used by the maintainers to triage
- P0 - Major broken functionality that causes a Bazel release (minus release
candidates) to be unusable, or a downed service that severely impacts
development of the Bazel project. This includes regressions introduced in a
new release that blocks a significant number of users, or an incompatible
breaking change that was not compliant to the Breaking
Change. No practical workaround exists.
- P1 - Critical defect or feature which should be addressed in the next
release, or a serious issue that impacts many users (including the development
of the Bazel project), but a practical workaround exists. Typically does not
require immediate action. In high demand and planned in the current quarter’s
- P2 - Defect or feature that is tied to roadmaps or upcoming releases.
Moderate live issue in a released Bazel version that is inconvenient for a
user that needs to be addressed in a upcoming release and/or a easy workaround
- P3 - Desirable minor bug fix or enhancement with small impact. Not
prioritized into Bazel roadmaps or any imminent release. May never be fixed.
- P4 - Low priority defect or feature request that is unlikely to get
closed. Can also be kept open for a potential re-prioritization if more users
For new issues, we deprecated the
category: * labels in favor of the team labels.
See the full list of labels here.