設計文件

回報問題 查看來源

如果您打算新增、變更或移除面向使用者的功能,或者對 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 即可更新現有文件。如有重大變更,應由文件審查者審查。任何人都能核准試用變更 (例如錯字、格式)。

審查者工作流程

審查者的留言、審查和核准設計文件。

一般審查員的責任

您必須負責審查設計文件、視需要要求提供額外資訊,並核准通過審查程序的設計。

收到新提案時

  1. 快速查看這份文件。
  2. 如果缺少重要資訊,或是設計與專案目標不符,請留言。
  3. 建議其他審查人員。
  4. 當 PR 準備就緒時,請予以核准。

在審查期間

  1. 與設計作者討論有問題或需要說明的問題。
  2. 如果可以,請邀請應瞭解設計的非審查人員留言。
  3. 決定哪些留言必須經過作者解決,做為核准的先決條件。
  4. 當您對提案目前的狀態感到滿意時,請在討論會話串中寫下「LGTM」(看起來不錯)。

所有設計審查要求都必須按照這個程序執行。如果設計未加入設計索引,請勿核准影響 Bazel 的設計。

待開發客戶審查人員的責任

您必須自行負責實作待處理設計。如果無法這樣做,則應找出適當的委派項目 (將 PR 重新指派給委派代表),或將錯誤重新指派給 Bazel Manager 以便進一步處理。

在審查期間

  1. 確保註解和設計疊代程序有建設性地進展。
  2. 在核准之前,請確保其他審查員的疑慮均已解決。

所有審查者核准後

  1. 確認郵寄清單上發布了至少 1 週的時間。
  2. 確認 PR 已更新狀態。
  3. 核准提案作者傳送的 PR。

拒絕設計

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