我們即將對 Bazel 進行破壞性變更，這並非難免。我們必須變更設計，並修正成效不彰的部分。但我們需要確保社群和 Bazel 生態系統可以持續發展。為此，Bazel 專案採用了回溯相容性政策。本文說明 Bazel 協作者為了遵守這項政策而在 Bazel 中進行破壞性變更的程序。
GitHub 問題
在 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
修訂版本也應更新相關說明文件，如此一來，修訂版本不會有程式碼與文件不一致的情形。我們的說明文件已發布版本，因此對文件所做的變更不會意外發布。
標籤
一旦合併修訂版本，且已準備好採用不相容的變更，請將 migration-ready 標籤新增至 GitHub 問題。
如果標記有問題，且使用者預計不會遷移，請移除標記 migration-ready。
如果您打算在下一個主要版本變更標記，請為問題加上「breaking-change-X.0」標籤。
更新存放區
Bazel CI 會將 Bazel@HEAD + Downstream 的重要專案清單進行測試。其中大部分工作通常是其他 Bazel 專案的依附元件，因此請務必遷移這些專案，以針對更廣泛的社群解除封鎖遷移作業。
如要監控這些專案的遷移狀態，您可以使用 bazelisk-plus-incompatible-flags 管道，並按這裡查看這個管道的運作方式。
在下游管道中遷移專案「不」不相容的變更作者負責。不過，您可以採取下列措施加快遷移速度，讓 Bazel 使用者和 Bazel Green Team 都能更輕鬆地處理工作。
- 提交 GitHub 問題，通知因不相容的變更導致下游專案的擁有者。
- 傳送 PR 以修正下游專案。
- 如需遷移方面的協助，請聯絡 Bazel 社群 (例如 Bazel Rules Authors SIG)。
翻轉旗幟
將旗標的預設值變成 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 中移除。如果您打算移除不相容的標記：
- 如果是不相容的重大異動，建議您延長使用者遷移時間。 在理想情況下，至少應可在一個主要版本中使用這個標記。
- 針對移除旗標的修訂版本，請在說明中使用
Fixes #abc，以便在合併修訂版本時關閉 GitHub 問題。