本页介绍了如何处理向后兼容性、 包括从一个版本迁移到另一个版本,以及如何 不兼容的更改。
Bazel 正在不断发展。作为 LTS 主要版本的一部分发布的次要版本完全向后兼容。新的主要 LTS 版本可能包含不兼容的变更,这些变更需要执行一些迁移工作。 有关 Bazel 发布模型的详情,请查看版本 模型页面。
摘要
- 建议使用
--incompatible_*
标志来进行破坏性更改。 - 对于每个
--incompatible_*
标志,GitHub 问题都会说明行为变更,并旨在提供迁移方案。 - 建议将不兼容的标志向后移植到最新 LTS 发布,而不启用该标志。
- 受
--experimental_*
标志保护的 API 和行为可能会随时发生变化 。 - 切勿使用
--experimental_*
或--incompatible_*
标志运行正式版 build。
如何遵守此政策
什么是稳定版功能?
通常,没有 --experimental_...
标志的 API 或行为被视为
运行稳定且受支持的功能
其中包括:
- Starlark 语言和 API
- 与 Bazel 捆绑的规则
- Bazel API,例如 Remote Execution API 或 Build Event Protocol
- 标志及其语义
不兼容的更改和迁移配方
对于新版本中每个不兼容的更改,Bazel 团队的目标是提供一个
迁移配方,可帮助您更新代码(BUILD
和 .bzl
文件,
以及脚本中使用的任何 Bazel、Bazel API 等)。
不兼容的更改应具有关联的 --incompatible_*
标志和
相应的 GitHub 问题。
建议将不兼容的标志和相关更改反向移植到 最新 LTS 版本,而不默认启用该标志。这样,用户 在下一个 LTS 版本推出之前进行迁移以解决不兼容的更改 可用。
传达不兼容的更改
有关不兼容更改的信息主要来源为 GitHub 问题 标有“incompatible-change” 标签。
对于每项不兼容的更改,问题都会指定以下内容:
- 控制不兼容更改的标志的名称
- 对更改的功能的说明
- 迁移方案
当不兼容的更改已准备好使用 HEAD 中的 Bazel 进行迁移时
(因此,对于下一个 Bazel 滚动版本而言),则应将其标记为
migration-ready
标签。在 HEAD 处将不兼容标志翻转后,不兼容更改问题会关闭。