我们不可避免地会对 Bazel 进行破坏性更改。我们必须更改设计,并修正不太理想的方面。不过,我们需要确保社区和 Bazel 生态系统能够跟上节奏。为此,Bazel 项目采用了向后兼容性政策。本文档介绍了 Bazel 贡献者的过程, 更改 Bazel 中的项目以遵守此政策
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 问题添加此标签后,它们将处理以下事项:
在 GitHub 问题中创建评论,以跟踪失败情况和需要迁移的下游项目的列表(请参阅示例)
提交 GitHub 问题,以通知因您的不兼容更改而遭到破坏的每个下游项目的所有者(请参阅示例)
进行跟进,确保在目标发布日期之前解决所有问题
向下游流水线中迁移项目并非完全由不兼容的更改作者负责,但您可以执行以下操作来加快迁移速度,并为 Bazel 用户和 Bazel Green 团队减轻工作负担。
发送 PR 来修复下游项目。
如需迁移方面的帮助,请与 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 问题。