我們勢必會對 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 管道。如要瞭解這個管道的運作方式，請參閱這篇文章。
我們的開發人員支援團隊會監控 migration-ready 標籤。將這個標籤新增至 GitHub 問題後，他們會處理下列事項：
在 GitHub 問題中建立留言，追蹤失敗清單和需要遷移的下游專案 (請參閱範例)
提交 GitHub 問題，通知因不相容變更而中斷的每個下游專案擁有者 (請參閱範例)
在目標發布日期前，追蹤並確保所有問題都已解決
下游管道中的專案遷移作業「並非」完全由不相容的變更作者負責，但您可以採取下列行動，加快遷移作業，並讓 Bazel 使用者和 Bazel Green 團隊的工作更輕鬆。
傳送 PR 來修正下游專案。
向 Bazel 社群尋求遷移方面的協助 (例如 Bazel 規則作者 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 問題就會關閉。