推出破壞性變更的指南

我們要對 Bazel 做出破壞性變更是不可避免的。我們必須變更設計並修正效果不彰的問題不過，我們需要確保社群與 Bazel 生態系統都能遵循為此 Bazel 專案採用了回溯相容性政策。本文件說明 Bazel 協作者如何做出破壞您在 Bazel 中進行的變更以遵守這項政策。

GitHub 問題

以下是建議做法：

標題會以標記名稱開頭 (標記名稱開頭為 incompatible_)。
將標籤 incompatible-change。
說明中包含變更的說明和相關連結設計文件
說明中包含遷移方案，可讓使用者瞭解更新程式碼理想情況下，如果採用的是機械式變更，則請在變更時遷移工具。
說明中包含了就算就無法遷移如此一來，就更容易從下列位置找到 GitHub 問題：。請確保錯誤訊息有幫助且可做為行動依據。可能的話，錯誤訊息應包含不相容的名稱旗標。

遷移工具時，請考慮使用以下工具：建構工具。可對 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。這些容器因此，請務必遷移這些專案，以免遷移作業擴大到更廣大的社群。如要監控這些專案的遷移狀態，您可以使用 bazelisk-plus-incompatible-flags 管道。如要瞭解這個管道的運作方式，請按這裡。

我們的開發支援團隊會監控 migration-ready 標籤。將這個標籤新增至 GitHub 問題後，團隊會處理下列事項：

至於遷移下游管道中的專案，「並」不算是不相容的變更作者，但您可以採取下列做法，加快遷移作業速度，讓 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 中移除。如果您打算移除不相容的標記：