我們無法對 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 Team 都更加輕鬆。
請傳送 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 問題。