在下列兩種情況下,Bazel Starlark 規則可能會破壞 Bazel LTS 版本的相容性:
- 這個規則依附於該 LTS 版本的相容性,因為需要使用該功能的功能已從 Bazel HEAD 中移除。
- 這項規則與舊版或 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 規則的作者,您可以遵循下列最佳做法,確保使用者能順利進行管理:
- 規則應遵循語意化版本管理:相同主要版本的次要版本具有回溯相容性。
- HEAD 規則應與最新的 Bazel LTS 版本相容。
- HEAD 的規則應與 Bazel 的 HEAD 相容。為達成此目標,您可以:
- 使用 Bazel 自行設定持續整合測試
- 將專案新增至 Bazel 下游測試;如果 Bazel 團隊破壞專案變更導致專案受到影響,您必須遵循我們的下游專案政策才能及時解決問題。
- 規則的最新主要版本必須與最新的 Bazel LTS 版本相容。
- 新的規則主要版本應與上個主要版本支援的最後一個 Bazel LTS 版本相容。
獲取 2. 和 3. 是最重要的工作,因為這樣可以達到 4. 和 5。自然而然
如要更輕鬆地與 Bazel HEAD 和最新的 Bazel LTS 版本相容,規則作者可:
- 要求回溯相容的功能,以便向後移植至最新的 LTS 版本,詳情請參閱發布程序。
- 使用 bazel_features 執行 Bazel 功能偵測。
一般而言,根據建議的做法,規則應能遷移 Bazel 不相容的變更,並在 HEAD 中使用新的 Bazel 功能,而不會與最新版 Bazel LTS 版本不相容。