推出破壞性變更的指南

回報問題 查看原始碼

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

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

  2. 與 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 問題。