我們即將對 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 問題。