如果您打算在 Bazel 中新增、變更或移除面向使用者的功能,或是對 Bazel 進行重大架構變更,則「必須」撰寫設計文件並通過審查,才能提交變更。
以下列舉幾項重大異動:
- 新增或刪除原生建構規則
- 原生規則的破壞性變更
- 變更會影響多個單一規則行為的原生建構規則語意
- Bazel 規則定義 API 的變更
- Bazel 用來連線至其他系統的 API 有異動
- Starlark 語言、語意或 API 的變更
- 可能會大幅影響 Bazel 效能或記憶體用量的變更 (改善或較差)
- 廣泛使用內部 API 的變更
- 旗標和指令列介面的變更。
設計審查的原因
撰寫設計文件時,您可以與其他 Bazel 開發人員協調合作,並向 Bazel 的核心團隊尋求指引。舉例來說,當提案新增、移除或修改 BUILD、WORKSPACE 或 bzl 檔案中的任何函式或物件時,請將 Starlark 團隊新增為審查人員。設計文件前必須先接受審查,原因如下:
- Bazel 是相當複雜的系統;看似無害的本機變更可能會對全球造成重大後果。
- 團隊會收到使用者提出的許多功能要求,這些要求除了要評估技術可行性,還涉及其他功能要求的重要性。
- Bazel 功能經常是由核心團隊以外的人員實作,這類貢獻者的 Bazel 專業知識各不相同。
- Bazel 團隊的專業能力各不相同,因此沒有一位團隊成員很瞭解 Bazel 的每個角落。
- 對 Bazel 所做的變更必須考量回溯相容性,並避免破壞性變更。
Bazel 的設計審查政策有助於盡可能達成以下目標:
- 對所有功能要求而言,我們都會取得基本程度的嚴格標準。
- 先確認理想人員的設計是否可行,再投注心力在設計可能效果不彰的實作上。
為協助您踏出第一步,請查看 Bazel Proposals Repository 中的設計文件。設計仍處於開發階段,因此實作詳細資料可能會隨時間變化以及意見回饋。已發布的設計文件會擷取初始設計,而不是在設計設計後持續產生的變更。請隨時參閱說明文件,瞭解目前 Bazel 功能的說明。
貢獻者工作流程
身為協作者,您可以撰寫設計文件、傳送提取要求並為提案要求審查者。
撰寫設計文件
所有設計文件都必須有包含下列內容的標頭:
- author
- 上次重大變化的日期
- 審查者清單,包括一位 (且僅限一位) 待開發客戶審查者
- 目前狀態 (draft、審查中、已核准、已遭拒、實作中、實作)
- 討論串連結 (在公告後加入)
文件可以採用可公開讀取的 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 相關文件以視覺方式保持一致。方法是依序點選「File」 >「Make a copy」,或點選這個連結,建立設計文件範本的副本。
如果想讓所有人都能讀取文件,請依序點選「Share」>「Advanced」>「Change...」,然後選擇「On - anyany the link」。如果允許在文件上加註,任何人都能匿名加註,即使沒有 Google 帳戶也不成問題。
使用 Markdown
文件會儲存在 GitHub 中,並採用 Markdown 的 GitHub 變種版本 (規格)。
建立 PR 來更新現有文件。重大變更應由文件審查人員審查。任何人都可能會核准測試性的變更 (例如錯字、格式),
審查者工作流程
審查人員留下意見、審核及核准設計文件。
一般審查人員的責任
您必須負責審查設計文件、視需要索取其他資訊,以及核准通過審核程序的設計。
收到新提案時
- 請快速查看文件。
- 如果缺少重要資訊,或是設計與專案目標不符時,就加上註解。
- 建議其他審查者。
- 在 PR 可供審查時進行核准。
審查期間
- 與設計作者討論有問題或需要進一步說明的問題。
- 如果適用,請邀請非審查人員提供的評論,他們應該瞭解設計。
- 決定哪些留言必須先由作者處理,才能獲得核准。
- 若您對目前的提案狀態感到滿意,請在討論串中撰寫「LGTM」(看起來不錯)。
所有設計審查要求都必須按照此流程進行。如果設計項目不在設計索引中,就不應核准會影響 Bazel 的設計。
待開發客戶審查者的責任
您必須負責決定實作待處理設計。如果您無法執行這項操作,則應找出合適的委派對象 (將 PR 重新指派給委派對象),或將錯誤重新指派給 Bazel 管理員,以便進一步處理。
審查期間
- 確保留言和設計疊代程序採取有建設性行動。
- 在核准之前,請確認其他審查人員的疑慮已解決。
所有審查者核准後
- 確認自郵件清單發布公告後,已至少提前 1 週。
- 確認 PR 已更新狀態。
- 核准提案作者傳送的 PR。
拒絕設計
- 確認公關作者傳送 PR,或將 PR 傳送給他們。
- 公關部門會更新文件狀態。
- 在文件中新增註解,說明設計無法在目前的狀態下通過核准的原因,以及視情況概述後續步驟 (例如「重新審視無效的假設並重新提交」)。