規則相容性

回報問題 查看原始碼 Nightly · 8.0 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

在下列兩種情況下，Bazel Starlark 規則可能會與 Bazel LTS 版本不相容：

  1. 由於所依附的功能已從 HEAD 版的 Bazel 中移除，因此這項規則會與日後的 LTS 版本不相容。
  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 設定自己的持續整合測試
    • 將專案加入 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 版本的相容性。