推出破壞性變更的指南

回報問題 查看原始碼 Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

我們勢必會對 Bazel 進行破壞性變更。我們必須變更設計，並修正效果不彰的問題。不過，我們需要確保社群和 Bazel 生態系統可以跟上腳步。為此，Bazel 專案採用了回溯相容性政策。本文件說明 Bazel 專案貢獻者如何遵循這項政策，在 Bazel 中進行重大變更。

  1. 遵循設計文件政策。

  2. 在 GitHub 提報問題。

  3. 實作變更。

  4. 更新標籤。

  5. 更新存放區。

  6. 將不相容標記翻轉。

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 問題後，團隊會處理下列事項：

  1. 在 GitHub 問題中建立留言，追蹤需要遷移的失敗項目和後續專案清單 (請參閱範例)

  2. 提交 GitHub 問題，通知所有下游專案擁有者，他們的專案因不相容的變更而中斷 (請參閱範例)

  3. 確認所有問題都已在目標發布日期前解決

遷移位於下游管道的專案並非不相容變更作者的責任，但您可以採取以下做法來加快遷移作業，讓 Bazel 使用者和 Bazel Green 團隊都更輕鬆。

  1. 傳送 PR 來修正下游專案。

  2. 請洽詢 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 問題。