規則相容性

回報問題 查看來源

在下列兩種情況中，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 是不可管理的，因為使用者需要同時升級規則_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 LTS 版本中維持與 Bazel 的相容性，規則作者可以：

  • 要求回溯相容功能，以向後移植至最新 LTS 版本。詳情請參閱發布程序。
  • 使用 bazel_features 執行 Bazel 功能偵測。

一般來說，透過我們建議的方法，規則應能遷移 Bazel 不相容的變更，並在 HEAD 上使用新的 Bazel 功能，而不會降低與最新 Bazel LTS 版本的相容性。