Skip to content

Latest commit

 

History

History
99 lines (65 loc) · 3.4 KB

breaking-changes-guide.md

File metadata and controls

99 lines (65 loc) · 3.4 KB
Raw
layout title
contribute
Guide for rolling out breaking changes

Guide for rolling out breaking changes

It is inevitable that we will make breaking changes to Bazel. We will have to change our designs and fix the things that do not quite work. However, we need to make sure that community and Bazel ecosystem can follow along. This document describes the process for Bazel contributors to make a breaking change in Bazel.

  1. Follow the design document policy.

  2. File a GitHub issue.

  3. Implement the change.

  4. Update labels

  5. Flip the incompatible flag.

GitHub issue

File a GitHub issue in the Bazel repository. See example.

  • The title starts with the name of the flag (the flag name will start with incompatible_).

  • Add the label incompatible-change.

  • The description contains a description of the change and a link to relevant design documents.

  • The description contains a migration recipe, to explain users how they should update their code. Ideally, when the change is mechanical, include a link to a migration tool.

  • The description includes the intended length of migration window.

For the migration tool, consider contributing to Buildifier. It is able to apply automated fixes to BUILD, WORKSPACE, and bzl files. It may also report warnings.

Implementation

Create a new flag in Bazel. The default value must be false. The help text should contain the URL of the GitHub issue. As the flag name starts with incompatible_, it needs metadata tags:

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
        OptionMetadataTag.TRIGGERED_BY_ALL_INCOMPATIBLE_CHANGES
      },

In the commit description, use RELNOTES: followed by a short description, the name of the flag, and a link to the GitHub issue.

Labels

Once the commit is merged, add the label migration-ready to the GitHub issue.

Later a Bazel release manager will update the issue and replace the label with migration-xx.yy.

The label breaking-change-xx.yy communicates when we plan to flip the flag. If a migration window needs to be extended, the author updates the label on GitHub issue accordingly.

If a problem is found with the flag and users are not expected to migrate yet: remove the flags migration-xx.yy.

Flipping the flag

Before flipping the default value of the flag to true, please make sure that:

  • The migration window is respected.
  • User concerns and questions have been resolved.
  • The flip will not break projects. Check the Bazelisk + Incompatible flags pipeline.

When changing the flag default to true, please:

  • Use RELNOTES: in the commit description, with the name the of the flag.
  • Use Fixes #xyz in the description, so that the GitHub issue gets closed when the commit is merged.

If a breakage is found after the flag flip, the commit will be rolled back.