向后兼容性

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

Bazel 在不断发展。作为 LTS 主要版本的一部分发布的次要版本完全向后兼容。主要 LTS 版本之间的更改可能包含不兼容的更改,需要进行一些迁移工作。如需详细了解 Bazel 发布频率,请参阅宣布推出 Bazel 长期支持 (LTS) 版本

摘要

  1. 建议使用 --incompatible_* 标志来表示重大变更。
  2. 对于每个 --incompatible_* 标志,GitHub 问题都会说明行为变化,并力求提供迁移方案。
  3. --experimental_* 标志保护的 API 和行为可能会随时更改。
  4. 切勿使用 --experimental_*--incompatible_* 标志运行正式版 build。

如何遵守本政策

什么是稳定功能?

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

其中包括:

  • Starlark 语言和 API
  • 与 Bazel 捆绑的规则
  • Bazel API,例如远程执行 API 或 build 事件协议
  • 标志及其语义

不兼容的更改和迁移方案

对于新版本中的每项不兼容的更改,Bazel 团队都会尽力提供迁移指南,帮助您更新代码(BUILD.bzl 文件,以及脚本中的任何 Bazel 用法、Bazel API 用法等)。

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

传达不兼容的更改

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

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

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

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