規則相容性

回報問題 查看來源

在下列兩種情況下，Bazel Starlark 規則可能會破壞 Bazel LTS 版本的相容性：

  1. 這個規則依附於該 LTS 版本的相容性，因為需要使用該功能的功能已從 Bazel HEAD 中移除。
  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 主要 CL
Bazel 4.x ✅ ❌ ❌ ❌
Bazel 5.x ❌ ✅ ✅ ❌
Bazel 6.x ❌ ❌ ✅ ✅
主要 CL ❌ ❌ ❌ ✅

❌：主要規則版本與 Bazel LTS 版本不相容。

✅：至少有一項規則與最新版的 Bazel LTS 版本相容。

最佳做法

身為 Bazel 規則的作者，您可以遵循下列最佳做法，確保使用者能順利進行管理：

  1. 規則應遵循語意化版本管理：相同主要版本的次要版本具有回溯相容性。
  2. HEAD 規則應與最新的 Bazel LTS 版本相容。
  3. HEAD 的規則應與 Bazel 的 HEAD 相容。為達成此目標，您可以：
    • 使用 Bazel 自行設定持續整合測試
    • 將專案新增至 Bazel 下游測試；如果 Bazel 團隊破壞專案變更導致專案受到影響，您必須遵循我們的下游專案政策才能及時解決問題。
  4. 規則的最新主要版本必須與最新的 Bazel LTS 版本相容。
  5. 新的規則主要版本應與上個主要版本支援的最後一個 Bazel LTS 版本相容。

獲取 2. 和 3. 是最重要的工作，因為這樣可以達到 4. 和 5。自然而然

如要更輕鬆地與 Bazel HEAD 和最新的 Bazel LTS 版本相容，規則作者可：

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

一般而言，根據建議的做法，規則應能遷移 Bazel 不相容的變更，並在 HEAD 中使用新的 Bazel 功能，而不會與最新版 Bazel LTS 版本不相容。