重大变更发布指南

我们对 Bazel 做出破坏性更改是不可避免的。我们必须更改设计,并修复不太奏效的方面。不过,我们需要确保社区和 Bazel 生态系统可以跟随我们一起步伐。为此,Bazel 项目采用了向后兼容性政策。本文档介绍了 Bazel 贡献者在 Bazel 中进行重大更改以遵循此政策的过程。

  1. 遵循设计文档政策

  2. 提交 GitHub 问题。

  3. 实施更改。

  4. 更新标签

  5. 翻转不兼容标志。

GitHub 问题

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

我们建议:

  • 标题以标志名称开头(标志名称以 incompatible_ 开头)。

  • 您添加标签 incompatible-change

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

  • 该说明包含一个迁移方法,向用户说明应如何更新其代码。理想情况下,如果是机械更改,请添加指向迁移工具的链接。

  • 该说明包含用户不迁移时将收到的错误消息示例。这会使 GitHub 问题更容易在搜索引擎中发现。请确保错误消息有用且可作为行动依据。 错误消息应尽可能包含不兼容标志的名称。

对于迁移工具,请考虑为 Buildifier 贡献代码。它能够对 BUILDWORKSPACE.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 + Downstream 中测试重要项目的列表。其中大多数通常是其他 Bazel 项目的依赖项,因此请务必进行迁移,以便为更广泛的社区解锁迁移能力。

如需监控这些项目的迁移状态,您可以使用 bazelisk-plus-incompatible-flags 流水线。如需查看此流水线的工作原理,请点击此处

在下游流水线中迁移项目并非完全由不兼容的变更作者负责。但您可以采取以下措施来加快迁移速度,并简化 Bazel 用户和 Bazel Green 团队的工作。

  1. 提交 GitHub 问题,通知因您的不兼容更改而损坏的下游项目的所有者。
  2. 发送 PR 来修复下游项目。
  3. 如需迁移方面的帮助,请与 Bazel 社区联系(例如,Bazel 规则作者 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 问题。