在以下两种情况下,Bazel Starlark 规则可能会破坏与 Bazel LTS 版本的兼容性:
- 该规则会破坏与未来 LTS 版本的兼容性,因为它所依赖的功能已从 HEAD 的 Bazel 中移除。
- 该规则会破坏与当前或旧版 LTS 的兼容性,因为它所依赖的功能仅在较新的 Bazel LTS 版本中可用。
同时,规则本身也可以为其用户发布不兼容的更改。与 Bazel 中的破坏性更改相结合时,升级规则版本和 Bazel 版本往往会让 Bazel 用户感到失望。本页面介绍了规则作者应如何保持规则与 Bazel 的兼容性,以便用户更轻松地升级 Bazel 和规则。
迁移过程易于管理
虽然保证每个 Bazel 版本与规则的每个版本之间的兼容性显然不可行,但我们的目标是确保 Bazel 用户的迁移过程仍然易于管理。可管理的迁移过程是指用户无需同时升级规则的主要版本和 Bazel 的主要版本的过程,这样一来,用户就可以一次处理来自一个来源的不兼容更改。
例如,对于以下兼容性矩阵:
- 从 rules_foo 1.x + Bazel 4.x 迁移到 rules_foo 2.x + Bazel 5.x,被视为不可管理,因为用户需要同时升级 rules_foo 和 Bazel 的主要版本。
- 从 rules_foo 2.x + Bazel 5.x 迁移到 rules_foo 3.x + Bazel 6.x 被视为是可管理的,因为用户可以先将 rules_foo 从 2.x 升级到 3.x,而无需更改 Bazel 主要版本,然后将 Bazel 从 5.x 升级到 6.x。
rules_foo 1.x | rules_foo 2.x | rules_foo 3.x | HEAD | |
---|---|---|---|---|
Bazel 4.x | ✅ | ❌ | ❌ | ❌ |
Bazel 5.x | ❌ | ✅ | ✅ | ❌ |
Bazel 6.x | ❌ | ❌ | ✅ | ✅ |
HEAD | ❌ | ❌ | ❌ | ✅ |
❌:主要规则版本没有与 Bazel LTS 版本兼容。
✅:至少有一个规则版本与最新版本的 Bazel LTS 兼容。
最佳实践
作为 Bazel 规则的编写者,您可以遵循以下最佳实践来确保迁移过程易于管理:
- 该规则应遵循语义版本控制:同一主要版本的次要版本向后兼容。
- HEAD 中的规则应与最新的 Bazel LTS 版本兼容。
- HEAD 中的规则应该与 HEAD 的 Bazel 兼容。为此,您可以
- 在 HEAD 中使用 Bazel 设置您自己的持续集成测试
- 将您的项目添加到 Bazel 下游测试中;如果 Bazel 中的重大更改影响了您的项目,Bazel 团队会向您的项目提交问题,并且您必须遵守我们的下游项目政策,以便及时解决问题。
- 该规则的最新主要版本必须与最新的 Bazel LTS 版本兼容。
- 规则的新主要版本应与该规则的先前主要版本支持的最新 Bazel LTS 版本兼容。
实现 2. 和 3. 是最重要的任务,因为这可以实现 4. 和 5.
为了更轻松地保持与 HEAD 的 Bazel 和最新的 Bazel LTS 版本的兼容性,规则作者可以执行以下操作:
- 请求将向后兼容的功能向后移植到最新的 LTS 版本,请查看发布流程以了解详情。
- 使用 bazel_features 执行 Bazel 功能检测。
一般来说,使用建议的方法后,规则应该能够针对与 Bazel 不兼容的更改进行迁移,并在 HEAD 中利用新的 Bazel 功能,而不会降低与最新 Bazel LTS 版本的兼容性。