如果您打算新增、變更或移除面向使用者的功能,或是對 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 來更新現有文件。文件審查人員應審查重大變更。任何人都可以核准微小變更 (例如錯字、格式)。
審查員工作流程
審查員會對設計文件加註、審查及核准。
一般審查者責任
您有責任審查設計文件、視需要要求提供額外資訊,以及核准通過審查程序的設計。
收到新提案時
- 快速瀏覽文件。
- 如果缺少重要資訊,或設計不符合專案目標,請留言。
- 建議其他審查者。
- 準備好審查時,請核准 PR。
審查程序期間
- 與設計作者討論有問題或需要釐清的事項。
- 如有需要,請邀請非審查員提供意見,讓他們瞭解設計。
- 決定作者必須先處理哪些留言,才能獲得核准。
- 如果對提案的現況感到滿意,請在討論串中輸入「LGTM」(Looks Good To Me)。
所有設計審查要求都必須經過這個程序。如果設計不在設計索引中,請勿核准影響 Bazel 的設計。
主要審查者責任
您負責決定是否要實作待處理的設計。如果無法執行這項操作,請找出合適的代表 (將 PR 重新指派給代表),或將錯誤重新指派給 Bazel 管理員,以進行後續處置。
審查程序期間
- 確保評論和設計迭代程序能以建設性的方式進行。
- 核准前,請確保已解決其他審查人員提出的疑慮。
所有審查者核准後
- 請確認郵寄清單發布公告後至少已過 1 週。
- 請確認 PR 會更新狀態。
- 核准提案作者傳送的 PR。
拒絕設計
- 確認 PR 作者傳送 PR,或傳送 PR 給他們。
- PR 會更新文件的狀態。
- 在文件中新增註解,說明設計目前無法通過核准的原因,並列出後續步驟 (例如「重新審查無效的假設並重新提交」)。