推出破壞性變更的指南

回報問題 查看原始碼 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 問題就會關閉。