重大变更发布指南

报告问题 查看源代码 每夜版 · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

我们必然会对 Bazel 进行重大更改。我们必须更改设计并修复不太正常的功能。不过，我们需要确保社区和 Bazel 生态系统能够跟上。为此，Bazel 项目已采用向后兼容性政策。本文档介绍了 Bazel 贡献者在 Bazel 中做出重大变更以遵守此政策的过程。

  1. 遵循设计文档政策。

  2. 提交 GitHub 问题。

  3. 实施更改。

  4. 更新标签。

  5. 更新代码库。

  6. 翻转不兼容标志。

GitHub 问题

在 Bazel 代码库中提交 GitHub 问题。 查看示例。

我们建议：

  • 标题以标志的名称开头（标志名称将以 incompatible_ 开头）。

  • 您添加了标签 incompatible-change。

  • 说明包含更改的描述以及指向相关设计文档的链接。

  • 说明包含迁移方案，用于向用户说明应如何更新代码。如果更改是机械性的，最好包含指向迁移工具的链接。

  • 说明中包含用户在不迁移时会收到的错误消息示例。这样一来，搜索引擎就能更容易发现该 GitHub 问题。确保错误消息实用且可操作。 如果可能，错误消息应包含不兼容标志的名称。

对于迁移工具，请考虑为 Buildifier 做出贡献。 它能够自动修复 BUILD、WORKSPACE 和 .bzl 文件。 它还可能会报告警告。

实现

在 Bazel 中创建新标志。默认值必须为 false。帮助文本应包含 GitHub 问题的网址。由于标志名称以 incompatible_ 开头，因此需要元数据标记：

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
      },

在提交说明中，添加标志的简要摘要。 还需添加以下形式的 RELNOTES:： RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details

提交还应更新相关文档，以便在提交窗口中，代码与文档保持一致。由于我们的文档是版本化的，因此文档的更改不会意外地过早发布。

标签

提交合并后，当不兼容的更改准备好被采用时，请向 GitHub 问题添加标签 migration-ready。

如果发现该标志存在问题，但用户尚不应迁移：请移除标志 migration-ready。

如果您计划在下一个主要版本中翻转该标志，请向问题添加标签“breaking-change-X.0”。

更新代码库

Bazel CI 会在 Bazel@HEAD + 下游中测试一系列重要项目。其中大多数通常是其他 Bazel 项目的依赖项，因此迁移它们对于更广泛的社区来说至关重要。如需监控这些项目的迁移状态，您可以使用 bazelisk-plus-incompatible-flags 流水线。点击此处即可了解此流水线的运作方式。

我们的开发者支持团队会监控 migration-ready 标签。将此标签添加到 GitHub 问题后，他们将处理以下事宜：

  1. 在 GitHub 问题中创建一条评论，以跟踪需要迁移的失败列表和下游项目（请参阅示例）

  2. 提交 GitHub 问题，以通知因您的不兼容性更改而中断的每个下游项目的所有者（请参阅示例）

  3. 跟进以确保在目标发布日期之前解决所有问题

下游流水线中的项目迁移并非完全由不兼容的变更作者负责，但您可以执行以下操作来加快迁移速度，并让 Bazel 用户和 Bazel Green 团队的工作更轻松。

  1. 发送 PR 以修复下游项目。

  2. 向 Bazel 社区寻求有关迁移的帮助（例如 Bazel Rules Authors SIG）。

翻转标志

在将标志的默认值翻转为 true 之前，请确保：

  • 迁移生态系统中的核心代码库。

    在 bazelisk-plus-incompatible-flags 流水线上，该标志应显示在 The following flags didn't break any passing Bazel team owned/co-owned projects 下。

  • 清单中的所有问题都标记为已修复/已关闭。

  • 用户疑虑和问题已解决。

如果 Bazel 中的标志已准备好翻转，但因 Google 内部迁移而受阻，请考虑在内部 blazerc 文件中将标志值设置为 false，以解除标志翻转的阻塞状态。这样一来，我们就可以确保 Bazel 用户尽早默认依赖于新行为。

将标志默认值更改为 true 时，请执行以下操作：

  • 在提交说明中使用 RELNOTES[INC]，格式如下：RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for details 您可以在提交说明的其余部分中添加其他信息。
  • 在说明中使用 Fixes #xyz，以便在合并提交时关闭 GitHub 问题。
  • 查看并根据需要更新文档。
  • 提交新问题 #abc 以跟踪标志的移除情况。

移除标志

在 HEAD 中翻转标志后，最终应从 Bazel 中移除该标志。 计划移除不兼容标志时：

  • 如果是不兼容的重大变更，请考虑为用户留出更多时间进行迁移。 理想情况下，该标志应至少在一个主要版本中可用。
  • 对于移除该标志的提交，请在说明中使用 Fixes #abc，以便在合并提交时关闭 GitHub 问题。