推出破壞性變更的指南

回報問題 查看來源 。 。 。 。 夜間。 。 7.3 。 。 7.2 。 。 7.1 。 。 7.0 。 。 6.5

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

  1. 遵守設計文件政策

  2. 回報 GitHub 問題。

  3. 執行變更。

  4. 更新標籤。

  5. 更新存放區。

  6. 翻轉不相容的旗幟。

GitHub 問題

回報 GitHub 問題 在 Bazel 存放區中執行 查看範例

以下是建議做法:

  • 標題會以標記名稱開頭 (標記名稱開頭為 incompatible_)。

  • 將標籤 incompatible-change

  • 說明中包含變更的說明和相關連結 設計文件

  • 說明中包含遷移方案,可讓使用者瞭解 更新程式碼理想情況下,如果採用的是機械式變更,則請在變更時 遷移工具。

  • 說明中包含了就算 就無法遷移如此一來,就更容易從下列位置找到 GitHub 問題: 。請確保錯誤訊息有幫助且可做為行動依據。 可能的話,錯誤訊息應包含不相容的名稱 旗標。

遷移工具時,請考慮使用以下工具: 建構工具。 可對 BUILDWORKSPACE.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。這些容器 因此,請務必遷移這些專案,以免遷移作業擴大到更廣大的社群。如要監控這些專案的遷移狀態,您可以使用 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 問題。