回溯相容性

回報問題open_in_new 查看原始碼open_in_new Nightly · 8.0 . 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

本頁面提供如何處理向後相容性的方式，包括從一個版本遷移至另一個版本，以及如何傳達不相容的變更。

Bazel 正在不斷演進。LTS 主要版本釋出的次要版本可完全回溯相容。新的 LTS 主要版本可能包含不相容的變更，需要進行一些遷移作業。如要進一步瞭解 Bazel 的版本模型，請參閱「版本模型」頁面。

摘要

1. 建議您使用 --incompatible_* 標記來進行重大變更。
2. 針對每個 --incompatible_* 旗標，GitHub 問題會說明行為變更，並提供遷移方法。
3. 建議將不相容的旗標回移至最新的 LTS 版本，但不要預設啟用旗標。
4. 由 --experimental_* 標記保護的 API 和行為隨時可能變更。
5. 請勿使用 --experimental_* 或 --incompatible_* 旗標執行正式版版本。

如何遵守這項政策

• 適用於 Bazel 使用者：如何更新 Bazel
• 針對貢獻者：不相容變更的最佳做法
• 適用於版本管理員：如何更新問題標籤和版本

什麼是穩定功能？

一般而言，沒有 --experimental_... 標記的 API 或行為，都會視為 Bazel 中穩定且支援的功能。

包括：

• Starlark 語言和 API
• 與 Bazel 一起提供的規則
• Bazel API，例如 Remote Execution API 或 Build Event Protocol
• 標記及其語意

不相容的變更和遷移方式

針對新版本中的每項不相容變更，Bazel 團隊都會提供遷移範例，協助您更新程式碼 (BUILD 和 .bzl 檔案，以及指令碼中的任何 Bazel 用途、Bazel API 用途等等)。

不相容的變更應具有相關聯的 --incompatible_* 標記和對應的 GitHub 問題。

建議將不相容的標記和相關變更回移至最新的 LTS 版本，但不預設啟用標記。這樣一來，使用者就能在下一個 LTS 版本推出前，先遷移不相容的變更。

傳達不相容的變更

如要瞭解不相容的變更，主要資訊來源是標示為 "incompatible-change" 標籤的 GitHub 問題。

每項不相容的變更都會在問題中指定下列資訊：

• 控制不相容變更的標記名稱
• 變更功能的說明
• 遷移配方

如果不相容的變更已準備好在 HEAD 中遷移至 Bazel (因此也適用於下一個 Bazel 滾動式版本)，則應標示為 migration-ready 標籤。當不相容標記在 HEAD 上翻轉時，不相容變更問題就會關閉。