向后兼容性

报告问题 查看源代码

本页介绍了如何处理向后兼容性(包括从一个版本迁移到另一个版本),以及如何传达不兼容的更改。

Bazel 在不断发展完善。作为 LTS 主要版本的一部分发布的次要版本完全向后兼容。新的主要 LTS 版本可能包含不兼容的更改,这些更改需要一些迁移工作。如需详细了解 Bazel 的发布模型,请查看发布模型页面。

摘要

  1. 建议使用 --incompatible_* 标志来实现破坏性更改。
  2. 对于每个 --incompatible_* 标志,GitHub 问题都会说明行为变更,并旨在提供迁移方案。
  3. 建议将不兼容的标志向后移植到最新的 LTS 版本,但不默认启用该标志。
  4. --experimental_* 标志保护的 API 和行为可能会随时更改。
  5. 切勿使用 --experimental_*--incompatible_* 标志运行正式版 build。

如何遵循此政策

什么是稳定版功能?

一般来说,不带 --experimental_... 标志的 API 或行为被视为 Bazel 中稳定且受支持的功能。

其中包括:

  • Starlark 语言和 API
  • 与 Bazel 捆绑的规则
  • Bazel API,例如 Remote Execution API 或构建事件协议
  • 标志及其语义

不兼容的更改和迁移方法

对于新版本中的每个不兼容更改,Bazel 团队旨在提供迁移方案,帮助您更新代码(BUILD.bzl 文件,以及脚本中的任何 Bazel 使用情况、Bazel API 的使用等)。

不兼容的更改应具有关联的 --incompatible_* 标志和相应的 GitHub 问题。

建议将不兼容的标志和相关更改向后移植到最新的 LTS 版本,而不默认启用该标志。这样,用户就可以在下一个 LTS 版本发布之前,针对不兼容的更改进行迁移。

传达不兼容的更改

不兼容更改的主要信息来源是带有“incompatible-change”标签的 GitHub 问题。

对于每项不兼容的更改,该问题都会指明以下内容:

  • 控制不兼容更改的标志的名称
  • 对更改的功能的说明
  • 迁移方案

当不兼容的更改准备好使用 HEAD 下的 Bazel 进行迁移时(因此,下一个 Bazel 滚动版本也会使用 migration-ready 标签进行标记)。在 HEAD 处翻转不兼容标志时,不兼容更改问题就关闭。