規則相容性

回報問題 查看來源

在下列兩種情況下，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 設定您自己的持續整合測試
   • 將專案新增至 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 版本相容。