我们不可避免地会对 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 + Downstream中测试一系列重要项目。其中大多数项目通常是其他 Bazel 项目的依赖项，因此将它们迁移对于解除更广泛社区的迁移障碍非常重要。如需监控这些项目的迁移状态，您可以使用 bazelisk-plus-incompatible-flags 流水线。
点击此处查看此流水线的工作原理。
我们的开发者支持团队会监控 migration-ready 标签。将此标签添加到 GitHub 问题后，他们将处理以下事项：
在 GitHub 问题中创建评论，以跟踪需要迁移的失败列表和下游项目（请参阅示例）
提交 GitHub 问题，以通知因不兼容的更改而中断的每个下游项目的所有者（请参阅示例）
跟进以确保在目标发布日期之前解决所有问题
下游流水线中的项目迁移并非完全由不兼容的更改作者负责，但您可以执行以下操作来加快迁移速度，并让 Bazel 用户和 Bazel Green 团队的工作更轻松。
发送 PR 以修复下游项目。
与 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 问题。