Guide for Bazel Maintainers

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 Bazel instead.

The objectives of this page are to:

  1. Serve as the maintainers’ source of truth for the project’s contribution process.
  2. Set expectations between the community contributors and the project maintainers.

Bazel’s core group of contributors has dedicated subteams to manage aspects of the open source project. These are:

  • Release Process: Manage Bazel’s release process.
  • Green Team: Grow a healthy ecosystem of rules and tools.
  • Developer Experience Gardeners: Encourage external contributions, review issues and pull requests, and make our development workflow more open.

Releases

Continuous Integration

Read the Green team’s guide to Bazel’s CI infrastructure on the bazelbuild/continuous-integration repository.

Lifecycle of an Issue

  1. A user creates an issue using the Issue Template and it enters the pool of unreviewed open issues.
  2. A member on the Developer Experience (DevEx) subteam rotation reviews the issue.
    1. If the issue is not a bug or a feature request, the DevEx member will usually close the issue and redirect the user to StackOverflow and bazel-discuss for higher visibility on the question.
    2. If the issue belongs in one of the rules repositories owned by the community, like rules_apple, the DevEx member will transfer this issue to the correct repository.
    3. 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 Template.
  3. 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.
  4. The DevEx member assigns the untriaged label and exactly one team label for routing.
  5. The DevEx member also assigns exactly one type: label, such as type: bug or type: feature request, according to the type of the issue.
  6. For platform-specific issues, the DevEx member assigns one platform: label, such as platform:apple for Mac-specific issues. At this stage, the issue enters the pool of untriaged open issues.

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 an owner of a team label, see this section for more information.

When an issue is resolved, it can be closed.

Lifecycle of a Pull Request

  1. A user creates a pull request.
  2. If you a member of a Bazel team and sending a PR against your own area, you are responsible for assigning your team label and finding the best reviewer.
  3. Otherwise, during daily triage, a DevEx member assigns one team label and the team’s technical lead (TL) for routing.
    1. The TL may optionally assign someone else to review the PR.
  4. The assigned reviewer reviews the PR and works with the author until it is approved or dropped.
  5. 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.
  6. If the imported commit passes all internal tests, the commit will be squashed and exported back out to GitHub.
  7. When the commit merges into master, GitHub automatically closes the PR.

My team owns a label. What should I do?

Subteams need to triage all issues in the labels they own, preferably on a weekly basis.

Issues

  1. Filter the list of issues by your team label and the untriaged label.
  2. Review the issue.
  3. Identify a priority level and assign the label.
  4. The issue may have already been prioritized by the DevEx subteam if it’s a P0. Re-prioritize if needed.
  5. Each issue needs to have exactly one priority label. If an issue is either P0 or P1 we assume that is actively worked on.
  6. Remove the untriaged label.

Note that you need to be in the bazelbuild organization to be able to add or remove labels.

Pull Requests

  1. Filter the list of pull requests by your team label.
  2. Review open pull requests.
  3. 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.
  4. Work with the pull request creator to complete a code review.
  5. Approve the PR.
  6. Ensure that all tests pass.
  7. Import the patch to the internal version control system and run the internal presubmits.
  8. Submit the internal patch. If the patch submits and exports successfully, the PR will be closed automatically by GitHub.

Priority

The following definitions for priority will be used by the maintainers to triage issues.

  • 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 policy. 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 roadmap.
  • P2 - Defect or feature that should be addressed but we don’t currently work on. Moderate live issue in a released Bazel version that is inconvenient for a user that needs to be addressed in an future release and/or a easy workaround exists.
  • 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 are impacted.
  • ice-box
    • Issues that we currently don’t have time to deal with nor the time to accept contributions. We will close these issues to indicate that nobody is working on them, but will continue to monitor their validity over time and revive them if enough people are impacted and if we happen to have resources to deal with them. As always, feel free to comment or add reactions to these issues even when closed.

Team labels

For new issues, we deprecated the category: * labels in favor of the team labels.

See the full list of labels here.