推出破壞性變更的指南

回報問題 查看來源

我們要對 Bazel 做出破壞性變更是不可避免的。我們必須變更設計，並修正效果不彰的問題。然而，我們必須確保社群和 Bazel 生態系統都能參與其中。為此，Bazel 專案採用了回溯相容性政策。本文件說明 Bazel 協作者在 Bazel 中做出破壞性變更的程序，以遵守這項政策。

  1. 遵守設計文件政策。

  2. 回報 GitHub 問題。

  3. 執行變更。

  4. 更新標籤。

  5. 更新存放區。

  6. 翻轉不相容的旗幟。

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

  1. 在 GitHub 問題中建立註解，追蹤需要遷移的失敗和下游專案清單 (參閱範例)

  2. 檔案 GitHub 問題，以通知因不相容的變更而中斷的每個下游專案擁有者 (查看範例)

  3. 進行後續追蹤，確保所有問題均已在目標發布日期前解決

至於遷移下游管道中的專案，「並」不算是不相容的變更作者，但您可以採取下列做法，加快遷移作業速度，讓 Bazel 使用者和 Bazel Green Team 作業更輕鬆。

  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 問題。