如果您打算新增、變更或移除面向使用者的功能,或者對 Bazel 進行重大架構變更,就「必須」撰寫設計文件並審查,然後才能提交變更。
以下列舉幾項重大異動:
- 新增或刪除原生建構規則
- 原生規則的破壞性變更
- 對原生建構規則語意所做的變更,影響了多個規則的行為
- Bazel 的規則定義 API 異動
- Bazel 用來連線至其他系統的 API 有所異動
- Starlark 語言、語意或 API 的變更
- 可能對 Bazel 效能或記憶體用量造成普遍影響的變更 (改善或降低)
- 大量使用的內部 API 變更
- 標記和指令列介面變更。
設計審查的原因
撰寫設計文件時,您可以與其他 Bazel 開發人員協調,並向 Bazel 核心團隊尋求指引。舉例來說,當提案新增、移除或修改 BUILD、WORKSPACE 或 bzl 檔案中可用的函式或物件時,請將 Starlark 團隊新增為審查人員。Google 會在提交前審查設計文件,原因如下:
- Bazel 是非常複雜的系統;看似無害的本機變更可能會產生重大的全球影響。
- 團隊會收到許多使用者要求的功能要求,因此除了技術可行性,也需要評估其他功能要求的重要性。
- Bazel 功能經常是由核心團隊以外的人員實作;這類貢獻者在 Bazel 專業知識方面有很大的差異。
- Bazel 團隊本身各有不同等級的專業知識,因此沒有單一團隊成員對 Bazel 的每個角落都擁有完整的瞭解。
- Bazel 的變更必須考量回溯相容性,並避免破壞性變更。
Bazel 的設計審查政策有助於盡可能提高以下情況:
- 所有功能要求都會獲得基本的審查基準。
- 這些設計人員在投入心力執行之前可能無法順利實行的設計工作
為協助您踏出第一步,請參閱 Bazel Ideas Repository 中的設計文件。我們正在進行設計,因此實作細節可能會隨時間而改變,並隨之改變。已發布的設計文件會擷取初始設計,而非在設計過程中進行中的變更。請務必參閱說明文件,瞭解目前 Bazel 功能的說明。
貢獻者工作流程
身為貢獻者,您可以撰寫設計文件、傳送提取要求,以及為提案提出審查要求。
撰寫設計文件
所有設計文件都必須具有包含以下內容的標頭:
- author
- 上次重大變更的日期
- 評論者清單,包括其中一位待開發客戶審查者
- 目前狀態 (草稿、審查中、已核准、已拒絕、已實作、實作)
- 討論串連結 (請在公告後加入)
文件可以採用全球可讀取的 Google 文件或使用 Markdown 編寫。請參閱下文,瞭解 Markdown / Google 文件的比較。
如果提案對使用者可察覺影響,必須具有說明對回溯相容性影響的部分 (以及視需要推出推出計畫) 的部分。
建立提取要求
建立提取要求 (PR) 以將文件新增至設計索引,藉此共用設計文件。將 Markdown 檔案或文件連結加入 PR 中。
盡可能選擇待開發客戶審查者,並將副本傳送給其他審查者。如果您並未選擇待開發客戶審查人員,Bazel 維護人員會將一位人員指派給您的 PR。
建立 PR 後,審查員可以在程式碼審查期間撰寫初步註解。例如,待開發客戶審查人員可以建議其他評論者,或指出遺漏的資訊。待開發客戶審查人員認為審查程序可以啟動後,就會核准公關。這不代表提案已經完全完善,或將獲得核准,代表提案包含足以展開討論所需的資訊。
發布新提案
提交 PR 時,將公告傳送至 bazel-dev。
您可以複製其他群組 (例如 bazel-discuss),以取得 Bazel 使用者的意見回饋。
與審查員反覆測試
任何感興趣的使用者都可以對您的提案留言。試著回答問題 釐清提案內容及解決疑慮
應在公告討論串中進行討論。如果提案是在 Google 文件中,可能會改用註解 (請注意,您允許使用匿名註解)。
更新狀態
在疊代作業完成後,建立新的 PR 以更新提案狀態。將 PR 傳送給相同的待開發客戶審查者,並將副本傳送給其他審查者。
如要正式接受提案,待開發客戶審查人員需先確定其他審查員同意了 PR 後,才會核准 PR。
從首份公告到提案核准之間至少需要 1 週。確保使用者有足夠時間閱讀文件並分享自己的疑慮。
實作提案可在接受提案前展開,例如概念驗證或實驗。不過,您無法在審查完成前提交變更。
選擇待開發客戶審查者
待開發客戶審查人員必須是下列領域的專家:
- 充分瞭解相關子系統
- 目標且有能力提供建設性意見
- 可在整個審查期間使用,以主導審查程序
建議您檢查各種團隊標籤的聯絡人。
Markdown 與 Google 文件
由於兩種系統都接受評估,請找出最適合您的方式。
使用 Google 文件的好處:
- 這項功能很容易上手,因此適合用來腦力激盪。
- 協作編輯。
- 快速疊代。
- 輕鬆提出修改建議。
使用 Markdown 檔案的好處:
- 乾淨用於連結的網址。
- 修訂版本的明確記錄。
- 即使在公開連結前忘記設定存取權限,也不用擔心。
- 輕鬆透過搜尋引擎搜尋資料。
- 未來保證:純文字文字本身不會用到任何特定工具,也不需要網路連線。
- 即使作者不再身邊,您也可以更新這些條款。
- 系統可能會自動處理這些要求 (更新/偵測無效連結、擷取作者清單等)。
您可以選擇先在 Google 文件中進行疊代,然後將其轉換為 Markdown,以用於待文。
使用 Google 文件
為保持一致性,請使用 Bazel 設計文件範本。該存放區包含必要的標頭,並能與其他 Bazel 相關文件建立視覺一致性。方法是依序點選「File」 >「Make a copy」,或點選這個連結建立設計文件範本的副本。
如要讓所有使用者都能讀取您的文件,請依序按一下「共用」>「進階」>「變更...」,然後選擇「開啟 - 任何知道連結的使用者」。如果您允許對文件發表留言,即使沒有 Google 帳戶,所有人也都能匿名加註。
使用 Markdown
文件會儲存在 GitHub 中,並使用 Markdown 的 GitHub 變種版本 (規格)。
建立 PR 即可更新現有文件。如有重大變更,應由文件審查者審查。任何人都能核准試用變更 (例如錯字、格式)。
審查者工作流程
審查者的留言、審查和核准設計文件。
一般審查員的責任
您必須負責審查設計文件、視需要要求提供額外資訊,並核准通過審查程序的設計。
收到新提案時
- 快速查看這份文件。
- 如果缺少重要資訊,或是設計與專案目標不符,請留言。
- 建議其他審查人員。
- 當 PR 準備就緒時,請予以核准。
在審查期間
- 與設計作者討論有問題或需要說明的問題。
- 如果可以,請邀請應瞭解設計的非審查人員留言。
- 決定哪些留言必須經過作者解決,做為核准的先決條件。
- 當您對提案目前的狀態感到滿意時,請在討論會話串中寫下「LGTM」(看起來不錯)。
所有設計審查要求都必須按照這個程序執行。如果設計未加入設計索引,請勿核准影響 Bazel 的設計。
待開發客戶審查人員的責任
您必須自行負責實作待處理設計。如果無法這樣做,則應找出適當的委派項目 (將 PR 重新指派給委派代表),或將錯誤重新指派給 Bazel Manager 以便進一步處理。
在審查期間
- 確保註解和設計疊代程序有建設性地進展。
- 在核准之前,請確保其他審查員的疑慮均已解決。
所有審查者核准後
- 確認郵寄清單上發布了至少 1 週的時間。
- 確認 PR 已更新狀態。
- 核准提案作者傳送的 PR。
拒絕設計
- 確認 PR 作者會傳送 PR,或是傳送 PR。
- PR 會更新文件狀態。
- 在文件中新增註解,說明設計無法在當前狀態下核准的原因,並列出後續步驟 (例如「重新審視無效的假設並重新提交」)。