我們勢必會對 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 團隊更輕鬆。
- 提交 GitHub 問題，通知因不相容變更而中斷的下游專案擁有者。
- 傳送 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 問題就會關閉。