Skip to content

Latest commit

 

History

History
229 lines (184 loc) · 11.5 KB

maintainers-guide.md

File metadata and controls

229 lines (184 loc) · 11.5 KB
Raw
layout title
contribute
Guide for Bazel Maintainers

Guide for Bazel Maintainers

Table of Contents

{:.no_toc}

  • ToC {:toc}

Overview

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 document 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:

  • User Onboarding: Improve the experience for new Bazel users, and help them get started.
  • 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 development.

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.
  3. If the issue is not a bug or a feature request, the DevEx member will close the issue and redirect the user to StackOverflow and bazel-discuss for higher visibility on the question.
  4. 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.
  5. 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.
  6. The DevEx member assigns the untriaged label and exactly one team label for routing.
  7. The DevEx member also assigns the bug or feature request label according to the type of the issue.

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 a 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.

Initial routing

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:

  1. Acknowledging the contributor's time and effort to open an issue or PR.
  2. Maximizing the visibility of the issue or PR towards domain experts.
  3. Reducing the maintainers' toil on sifting through the large volume of issues and PRs.

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 @bazelbuild/devex alias.

Routed issues must have:

  1. a team label, e.g. team-Starlark
  2. either the untriaged label OR one priority label (p0, p1, p2, p3, p4), but not both.

The exceptions to this are issues for tracking releases and incompatible changes.

See the list of issues to be routed here.

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.

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. 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. No practical workaround exists. policy.
  • 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 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 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.

Team labels

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

See the full list of labels here.