重大变更发布指南

<ph type="x-smartling-placeholder"></ph> 报告问题 查看来源 敬上 每晚 · 7.3。 · 7.2 条 · 7.1敬上 · 7.0。 · 6.5

我们不可避免地会对 Bazel 做出破坏性更改。我们必须 改变我们的设计，修复无法正常运行的问题。不过，我们需要 以确保社区和 Bazel 生态系统协调一致。为此， Bazel 项目采用了 向后兼容性政策。 本文档介绍了 Bazel 贡献者的过程， 在 Bazel 中进行更改以符合此政策

  1. 遵循设计文档政策。

  2. 提交 GitHub 问题。

  3. 实施更改。

  4. 更新标签。

  5. 更新代码库。

  6. 翻转不兼容的标记。

GitHub 问题

提交 GitHub 问题 运行 GCP 控制台 查看示例。

我们建议：

  • 标题以旗帜名称开头（旗帜名称以 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

提交时还应更新相关文档，以确保 提交窗口中的代码与文档不一致。由于我们的 文档有版本编号，对文档的更改不会意外 过早发布

标签

在提交合并且不兼容的更改可供采用后，添加标签 migration-ready GitHub 问题

如果发现该标志存在问题，并且预计用户不会迁移，请执行以下操作： 移除 migration-ready 标志。

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

更新代码库

Bazel CI 会测试 Google Cloud 上的 Bazel@HEAD + 下游。大多数情况下 其他 Bazel 项目的依赖项，因此请务必迁移这些 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 问题。