本頁面說明如何處理回溯相容性,包括從某版本遷移至另一個版本,以及如何傳送不相容的變更。
Bazel 正在演進中。LTS 主要版本中發布的子版本完全回溯相容。新的主要 LTS 版本可能包含不相容的變更,需要一些遷移才能完成。如要進一步瞭解 Bazel 的發布模型,請參閱發布模型頁面。
摘要
- 建議您使用
--incompatible_*
旗標處理破壞性變更。 - 每個
--incompatible_*
旗標都有一個 GitHub 問題說明行為的變化,以提供遷移方案。 - 建議將不相容的標記向後移植至最新的 LTS 版本,但不預設啟用該標記。
- 由
--experimental_*
旗標保護的 API 和行為可能隨時變更。 - 切勿使用
--experimental_*
或--incompatible_*
旗標執行實際工作環境版本。
如何遵守這項政策
什麼是穩定功能?
一般來說,沒有 --experimental_...
旗標的 API 或行為會視為 Bazel 中支援的穩定功能。
包括:
- Starlark 語言和 API
- Bazel 隨附的規則
- Bazel API,例如 Remote Execution API 或建構事件通訊協定
- 旗標及其語意
不相容的變更和遷移方案
針對新版本中的每個不相容的變更,Bazel 團隊的目標是提供遷移方案,協助您更新程式碼 (BUILD
和 .bzl
檔案,以及指令碼中的 Bazel 使用情形、Bazel API 使用情形等)。
不相容的變更應有相關聯的 --incompatible_*
旗標和對應的 GitHub 問題。
不相容的標記和相關變更建議向後移植至最新的 LTS 版本,但不預設啟用該標記。這麼做可讓使用者在下一個 LTS 版本推出前,遷移不相容的變更。
傳送不相容的變更
關於不相容變更的主要資訊來源是 GitHub 問題,該問題會標示「不相容的變更」標籤。
針對所有不相容的變更,必須指出下列問題:
- 控制不相容變更的標記名稱
- 功能變更的說明
- 遷移方案
如果不相容的變更已準備好在 HEAD 使用 Bazel (因此還有下一個 Bazel 滾動版本),就會標示 migration-ready
標籤。當不相容的標記在 HEAD 遭到翻轉時,就會關閉不相容的變更問題。