本頁說明如何處理回溯相容性,包括從某個版本遷移至另一個版本,以及如何傳達不相容的變更。
Bazel 正不斷進化。LTS 主要版本發布的子版本可完全回溯相容。主要 LTS 版本的變更可能包含不相容的變更,因此需要部分遷移工作。如要進一步瞭解 Bazel 發布頻率的運作方式,請參閱宣布 Bazel 長期支援 (LTS) 版本。
摘要
- 建議您使用
--incompatible_*
旗標進行破壞性變更。 - 針對每個
--incompatible_*
標記,GitHub 問題會說明行為的變化,並致力提供遷移方案。 - 由
--experimental_*
旗標保護的 API 和行為隨時可能變更。 - 切勿執行具有
--experimental_*
或--incompatible_*
旗標的實際工作環境版本。
如何遵守這項政策
什麼是穩定功能?
一般來說,不含 --experimental_...
標記的 API 或行為會視為穩定且 Bazel 支援的功能。
違規的行為與內容包括:
- Starlark 語言與 API
- Bazel 附帶的規則
- Bazel API,例如 Remote Execution API 或 Build Event 通訊協定
- 旗標及其語意
不相容的變更和遷移方案
對於新版本的所有不相容的變更,Bazel 團隊都會致力提供「遷移方案」來協助您更新程式碼 (BUILD
和 .bzl
檔案,以及指令碼中的任何 Bazel 用量、使用 Bazel API 等)。
不相容的變更應有相關聯的 --incompatible_*
旗標和對應的 GitHub 問題。
傳送不相容的變更
不相容變更資訊的主要來源是 GitHub 問題 (標有「不相容變更」標籤)。
每個不相容的變更都會指出以下項目:
- 控制不相容變更的旗標名稱
- 功能異動說明
- 遷移方案
當 Bazel 在 HEAD 元素 (也包含下一個 Bazel 滾動式版本) 可遷移不相容的變更時,則應加上 migration-ready
標籤。如果在 HEAD 上翻轉了不相容的標記,就會關閉不相容的變更問題。