重大变更发布指南

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

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

  1. 遵循设计文档政策。

  2. 提交 GitHub 问题。

  3. 实施更改。

  4. 更新标签。

  5. 更新代码库。

  6. 翻转不兼容的标记。

GitHub 问题

提交 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

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

标签

在提交合并且不兼容的更改可供采用后，添加标签 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 问题。