我們要對 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
該次提交也應更新相關說明文件,以免發生程式碼與說明文件不一致的提交時段。由於說明文件有版本控制,因此不會不小心提前發布變更。
標籤
合併修訂版本後,如果不相容的變更已準備好採用,請在 GitHub 問題中新增標籤 migration-ready
。
如果發現標記有問題,但使用者尚未遷移:
移除標記 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 問題就會關閉。