我们不可避免地会对 Bazel 进行破坏性更改。我们必须更改设计，并修正效果不佳的方面。但是，我们需要确保社区和 Bazel 生态系统能够持续开展相关工作。为此，Bazel 项目采用了向后兼容性政策。本文档介绍了 Bazel 贡献者为遵守此政策而在 Bazel 中进行破坏性更改的流程。
GitHub 问题
在 Bazel 代码库中提交 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
提交操作还应更新相关文档，以免代码与文档不一致。由于我们的文档采用版本控制，因此不会无意中过早发布对文档所做的更改。
标签
提交内容合并后，如果不兼容的更改已准备好采用，请为 GitHub 问题添加标签 migration-ready。
如果发现标志存在问题，并且用户尚未准备好迁移，请移除标志 migration-ready。
如果您计划在下一个主要版本中翻转该标志，请为该问题添加标签“breaking-change-X.0”。
更新代码库
Bazel CI 会在 Bazel@HEAD + 下游环境中测试一系列重要项目。其中大多数通常是其他 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 问题。