规则兼容性

报告问题 查看源代码

在以下两种情况下，Bazel Starlark 规则可能会破坏与 Bazel LTS 版本的兼容性：

  1. 该规则会破坏与未来 LTS 版本的兼容性，因为它所依赖的功能已从 HEAD 的 Bazel 中移除。
  2. 该规则会破坏与当前或更低版本的 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 规则的创建者，您可以遵循以下最佳实践，确保用户拥有可管理的迁移流程：

  1. 该规则应遵循语义版本控制：同一主要版本的次要版本向后兼容。
  2. HEAD 中的规则应与最新的 Bazel LTS 版本兼容。
  3. HEAD 中的规则应该与 HEAD 中的 Bazel 兼容。为此，您可以：
    • 在 HEAD 上利用 Bazel 设置您自己的 CI 测试
    • 将您的项目添加到 Bazel 下游测试；如果 Bazel 的破坏性更改影响到您的项目，则 Bazel 团队会向您的项目提交问题；您必须遵循我们的下游项目政策及时解决问题。
  4. 该规则的最新主要版本必须与最新的 Bazel LTS 版本兼容。
  5. 该规则的新主要版本应与该规则先前的主要版本支持的最后一个 Bazel LTS 版本兼容。

实现第 2 条和第 3 条是最重要的任务，因为它可以实现第 4 条和第 5 条。当然了。

为了更轻松地与 HEAD 中的 Bazel 和最新的 Bazel LTS 版本保持兼容，规则作者可以：

  • 请求向后兼容的功能，以向后移植到最新的 LTS 版本。如需了解详情，请查看发布流程。
  • 使用 bazel_features 执行 Bazel 特征检测。

通常，采用推荐的方法时，规则应该能够迁移以与 Bazel 不兼容的更改，并在 HEAD 中使用新的 Bazel 功能，并且不会与最新的 Bazel LTS 版本兼容。