我們要對 Bazel 做出破壞性變更是不可避免的。我們必須變更設計,並修正效果不彰的問題。然而,我們必須確保社群和 Bazel 生態系統都能參與其中。為此,Bazel 專案採用了回溯相容性政策。本文件說明 Bazel 協作者在 Bazel 中做出破壞性變更的程序,以遵守這項政策。
GitHub 問題
在 Bazel 存放區中回報 GitHub 問題。查看範例。
以下是建議做法:
標題會以標記名稱開頭 (標記名稱的開頭為
incompatible_
)。您可以新增
incompatible-change
標籤,說明包含變更的說明以及相關設計文件的連結。
說明中包含遷移方案,可讓使用者瞭解如何更新程式碼。在理想情況下,如果變更是機械,請附上遷移工具的連結。
說明中包括未遷移使用者會收到的錯誤訊息示例。如此一來,搜尋引擎就能更容易找到 GitHub 問題。請確保錯誤訊息有幫助且可做為行動依據。如果可以,錯誤訊息應包含不相容標記的名稱。
建議您對遷移工具貢獻一己之力,對建構工具貢獻一己之力。可對 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 Team 作業更輕鬆。
傳送 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 問題。