本頁說明如何處理回溯相容性,包括從某個版本遷移至另一個版本,以及如何傳達不相容的變更。
Bazel 正不斷進化。LTS 主要版本發布的子版本可完全回溯相容。新的主要 LTS 版本可能包含不相容的變更,需要一些遷移工作。如要進一步瞭解 Bazel 的發布模型,請參閱發布模型頁面。
摘要
- 建議您使用
--incompatible_*
旗標進行破壞性變更。 - 針對每個
--incompatible_*
標記,GitHub 問題會說明行為變更,並致力提供遷移方案。 - 使用不相容的標記,建議在不預設啟用此標記的情況下,向後移植到最新的 LTS 版本。
- 由
--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 問題。
建議使用不相容的標記和相關的變更,以便向後移植到最新的 LTS 版本,而不預設啟用標記。這可讓使用者在下一個 LTS 版本推出前,針對不相容的變更進行遷移。
傳送不相容的變更
不相容變更資訊的主要來源是 GitHub 問題 (標有「不相容的變更」標籤)。
每個不相容的變更都會指出以下項目:
- 控制不相容變更的旗標名稱
- 功能異動說明
- 遷移方案
當 Bazel 在 HEAD 元素 (也包含下一個 Bazel 滾動式版本) 準備好遷移不相容的變更時,則應標示 migration-ready
標籤。如果在 HEAD 上翻轉不相容的標記,就會關閉不相容的變更問題。