設計文件

回報問題 查看來源 Nightly · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

如果您打算新增、變更或移除面向使用者的功能,或是對 Bazel 進行重大架構變更,則必須先撰寫設計文件並通過審查,才能提交變更。

重大變更的例子如下:

  • 新增或刪除原生建構規則
  • 原生規則的重大變更
  • 原生建構規則語意變更,影響多個規則的行為
  • Bazel 規則定義 API 的異動
  • Bazel 用於連線至其他系統的 API 變更
  • Starlark 語言、語意或 API 的變更
  • 可能對 Bazel 效能或記憶體用量造成全面影響的變更 (無論好壞)
  • 廣泛使用的內部 API 變更
  • 變更標記和指令列介面。

設計審查的原因

撰寫設計文件時,您可以與其他 Bazel 開發人員協調,並向 Bazel 核心團隊尋求指引。舉例來說,如果提案在 BUILD、MODULE.bazel 或 bzl 檔案中新增、移除或修改任何函式或物件,請將 Starlark 團隊新增為審查人員。設計文件必須先經過審查才能提交,原因如下:

  • Bazel 是非常複雜的系統,看似無害的本機變更可能會造成重大的全域影響。
  • 團隊收到許多使用者提出的功能要求,因此不僅需要評估技術可行性,還必須考量這些要求相較於其他要求的重要性。
  • Bazel 功能通常是由核心團隊以外的人員實作,這些貢獻者的 Bazel 專業知識程度差異很大。
  • Bazel 團隊本身的專業知識程度不一,沒有任何一位團隊成員完全瞭解 Bazel 的每個角落。
  • Bazel 的變更必須考量回溯相容性,並避免破壞性變更。

Bazel 的設計審查政策有助於盡可能確保:

  • 所有功能要求都會經過基本審查。
  • 在我們投入實作前,合適的人員會先評估設計,確保不會白費力氣。

如要開始使用,請參閱 Bazel Proposals Repository 中的設計文件。設計仍在開發階段,因此實作細節可能會隨著時間和意見回饋而有所變更。發布的設計文件會擷取初始設計,不會擷取設計實作期間的持續變更。如需目前 Bazel 功能的說明,請一律參閱文件。

貢獻者工作流程

身為貢獻者,您可以撰寫設計文件、傳送提取要求,以及要求審查者審查提案。

撰寫設計文件

所有設計文件都必須包含以下標題:

  • 作者
  • 上次重大變更的日期
  • 審查員清單,包括一位 (且僅一位)主要審查員
  • 目前狀態 (草稿審查中已核准已拒絕實施中已實施)
  • 討論串連結 (公告發布後再新增)

文件可以是全球可讀取的 Google 文件,也可以使用 Markdown 撰寫。請參閱下方的 Markdown / Google 文件比較

如果提案會對使用者造成影響,則必須包含一個章節,記錄對回溯相容性的影響 (如有需要,也請附上推出計畫)。

建立提取要求

建立提取要求 (PR),將設計文件新增至設計索引,即可分享設計文件。將 Markdown 檔案或文件連結新增至 PR。

盡可能選擇主要審查員, 並將其他審查員加入副本。如未選擇主要審查者,Bazel 維護人員會為您的 PR 指派審查者。

建立 PR 後,審查人員可以在程式碼審查期間提出初步意見。舉例來說,主要審查員可以建議新增審查員,或指出缺少資訊。當主要審查員認為可以開始審查程序時,就會核准 PR。這不代表提案完美無缺或一定會獲得核准,而是提案包含足夠的資訊,可供開始討論。

宣布新提案

提交 PR 時,向 bazel-dev 發送公告。

您可以複製其他群組 (例如 bazel-discuss),向 Bazel 終端使用者徵求意見。

與審查者一起反覆修改

有興趣的人都可以對提案加註。盡量回答問題、釐清提案內容,並解決疑慮。

討論應在公告討論串中進行。如果提案位於 Google 文件中,則可改用註解 (請注意,系統允許匿名註解)。

更新狀態

完成疊代後,請建立新的 PR 來更新提案狀態。將 PR 傳送給同一位主要審查者,並將其他審查者加入副本。

如要正式接受提案,主審人員必須先確認其他審查人員同意這項決定,然後核准 PR。

從首次公告到提案獲准,至少須間隔 1 週。確保使用者有足夠時間閱讀文件並提出疑慮。

提案獲准前即可開始實作,例如概念驗證或實驗。不過,審查完成前,您無法提交變更。

選擇主要審查者

主要審查員應為領域專家,且:

  • 熟悉相關子系統
  • 客觀且能提供建設性意見
  • 在整個審查期間負責主導程序

建議檢查各種團隊標籤的聯絡人。

Markdown 與 Google 文件

兩種方式都可接受,請選擇最適合自己的做法。

使用 Google 文件的優點:

  • 適合腦力激盪,因為很容易上手。
  • 協作編輯。
  • 快速疊代。
  • 輕鬆提出編輯建議。

使用 Markdown 檔案的好處:

  • 用於連結的簡短網址。
  • 明確的修訂記錄。
  • 發布連結前,不會忘記設定存取權。
  • 方便搜尋引擎檢索。
  • 不受特定工具限制:純文字不受任何特定工具限制,也不需要網際網路連線。
  • 即使作者不在,您也可以更新這些檔案。
  • 系統會自動處理這些連結 (更新/偵測無效連結、擷取作者清單等)。

您可以先在 Google 文件中反覆修改,然後轉換為 Markdown 格式,以供日後使用。

使用 Google 文件

為確保一致性,請使用 Bazel 設計文件範本。其中包含必要的標題,並與其他 Bazel 相關文件建立視覺一致性。如要這麼做,請依序點選「檔案」 >「建立副本」,或按一下這個連結建立設計文件範本副本

如要讓全世界都能閱讀文件,請依序按一下「共用」>「進階」>「變更…」,然後選擇「開啟 - 任何知道連結的使用者」。如果允許在文件中加入註解,任何人都可以匿名留言,即使沒有 Google 帳戶也沒問題。

使用 Markdown

文件儲存在 GitHub 上,並使用 GitHub 版本的 Markdown (規格)。

建立 PR 來更新現有文件。文件審查人員應審查重大變更。任何人都可以核准微小變更 (例如錯字、格式)。

審查員工作流程

審查員會對設計文件加註、審查及核准。

一般審查者責任

您有責任審查設計文件、視需要要求提供額外資訊,以及核准通過審查程序的設計。

收到新提案時

  1. 快速瀏覽文件。
  2. 如果缺少重要資訊,或設計不符合專案目標,請留言。
  3. 建議其他審查者。
  4. 準備好審查時,請核准 PR。

審查程序期間

  1. 與設計作者討論有問題或需要釐清的事項。
  2. 如有需要,請邀請非審查員提供意見,讓他們瞭解設計。
  3. 決定作者必須先處理哪些留言,才能獲得核准。
  4. 如果對提案的現況感到滿意,請在討論串中輸入「LGTM」(Looks Good To Me)。

所有設計審查要求都必須經過這個程序。如果設計不在設計索引中,請勿核准影響 Bazel 的設計。

主要審查者責任

您負責決定是否要實作待處理的設計。如果無法執行這項操作,請找出合適的代表 (將 PR 重新指派給代表),或將錯誤重新指派給 Bazel 管理員,以進行後續處置。

審查程序期間

  1. 確保評論和設計迭代程序能以建設性的方式進行。
  2. 核准前,請確保已解決其他審查人員提出的疑慮。

所有審查者核准後

  1. 請確認郵寄清單發布公告後至少已過 1 週。
  2. 請確認 PR 會更新狀態。
  3. 核准提案作者傳送的 PR。

拒絕設計

  1. 確認 PR 作者傳送 PR,或傳送 PR 給他們。
  2. PR 會更新文件的狀態。
  3. 在文件中新增註解,說明設計目前無法通過核准的原因,並列出後續步驟 (例如「重新審查無效的假設並重新提交」)。