推出破壞性變更的指南

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

我們勢必會對 Bazel 進行破壞性變更。我們必須修改設計，並修正無法正常運作的部分。不過，我們需要確保社群和 Bazel 生態系統可以跟上腳步。為此，Bazel 專案採用了回溯相容性政策。本文件說明 Bazel 專案貢獻者如何遵循這項政策，在 Bazel 中進行重大變更。

GitHub 問題

建議您：

標題開頭為標記名稱 (標記名稱開頭為 incompatible_)。
您新增了標籤 incompatible-change。
說明包含變更說明和相關設計文件的連結。
說明中包含遷移食譜，向使用者說明如何更新程式碼。理想情況下，如果變更是機械性的，請附上遷移工具的連結。
說明中會提供使用者未遷移時會收到的錯誤訊息範例。這樣一來，搜尋引擎就能更容易找到 GitHub 問題。請確認錯誤訊息有幫助且可採取行動。盡可能在錯誤訊息中加入不相容標記的名稱。

如要使用遷移工具，請考慮為 Buildifier 做出貢獻。這項工具可將自動修正項目套用至 BUILD、WORKSPACE 和 .bzl 檔案。也可能會回報警告。

在 Bazel 中建立新的標記。預設值必須為 false。說明文字應包含 GitHub 問題的網址。由於標記名稱開頭為 incompatible_，因此需要中繼資料標記：

      metadataTags = {
        OptionMetadataTag.INCOMPATIBLE_CHANGE,
      },

在提交說明中，簡要說明標記。並在下列表單中新增 RELNOTES:： RELNOTES: --incompatible_name_of_flag has been added. See #xyz for details

該次提交也應更新相關說明文件，以免發生程式碼與說明文件不一致的提交時段。由於說明文件有版本控制，因此不會不小心提前發布變更。

Bazel CI 會在 Bazel@HEAD + Downstream 測試一長串重要專案。這些依附元件通常是其他 Bazel 專案的依附元件，因此必須遷移這些依附元件，才能讓更廣大的社群解除遷移作業的封鎖。

如要監控這些專案的遷移狀態，您可以使用 bazelisk-plus-incompatible-flags 管道，請參閱這篇文章瞭解管道的運作方式。

遷移下游管道中的專案並非不相容變更作者的責任。不過，您可以採取下列做法加快遷移作業，讓 Bazel 使用者和 Bazel Green Team 都能更輕鬆地進行遷移。

將標記的預設值切換為 true 之前，請確認下列事項：

遷移生態系統中的核心存放區。

在 bazelisk-plus-incompatible-flags 管道中，標記應顯示在 The following flags didn't break any passing Bazel team owned/co-owned projects 下方。
使用者疑慮和問題已解決。

如果標記已準備好在 Bazel 中切換，但在 Google 內部遷移時遭到封鎖，請考慮在內部 blazerc 檔案中將標記值設為 false，以解除標記切換的封鎖。這樣一來，我們就能確保 Bazel 使用者盡早採用新的預設行為。

將標記預設值變更為 true 時，請注意：

在修訂版本說明中使用 RELNOTES[INC]，格式如下： RELNOTES[INC]: --incompatible_name_of_flag is flipped to true. See #xyz for details 您可以在其餘修訂版本說明中加入其他資訊。
在說明中使用 Fixes #xyz，這樣在合併修訂版本時，GitHub 問題就會關閉。
視需要查看及更新說明文件。
請提出新問題 #abc，以便追蹤移除標記的進度。

在 HEAD 中切換標記後，應最終從 Bazel 中移除。如要移除不相容標記，請注意以下事項：