重大变更发布指南

报告问题 查看源代码

我们不可避免地对 Bazel 做出破坏性更改。我们必须更改设计并修复效果不佳的部分。但是,我们需要确保社区和 Bazel 生态系统可以跟上发展步伐。为此,Bazel 项目采用了向后兼容政策。本文档介绍了 Bazel 贡献者在 Bazel 中做出重大更改以遵守此政策的过程。

  1. 遵循设计文档政策

  2. 提交 GitHub 问题

  3. 实施更改。

  4. 更新标签。

  5. 更新代码库

  6. 翻转不兼容的标志

GitHub 问题

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

我们建议:

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

  • 您需要添加标签 incompatible-change

  • 该说明包含变更说明和相关设计文档的链接。

  • 该说明包含一个迁移方案,用于说明用户应如何更新代码。理想情况下,如果更改需要借助机械完成,请包含指向迁移工具的链接。

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

对于迁移工具,请考虑为构建器做贡献。能够对 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 + 下游测试重要项目列表。其中大多数依赖项通常是其他 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 问题。