設計文件

回報問題 查看來源 。 。 夜間。 。 7.3 。 。 7.2 。 。 7.1 。 。 7.0 。 。 6.5

若您打算新增、變更或移除面向使用者的功能 使用 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 功能說明的說明文件

貢獻者工作流程

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

撰寫設計文件

所有設計文件都必須具有包含以下內容的標頭:

  • 作者
  • 上次重大變更的日期
  • 評論者清單,包括一份 (且僅限一個) 待開發客戶評論者
  • 目前狀態 (草稿審查中已核准已拒絕導入)
  • 討論串連結 (請在公告後加入)

這份文件可以編寫為可供全球使用者閱讀的 Google 文件使用 Markdown。請閱讀以下內容 Markdown / Google 文件比較

如果提案對使用者的影響不可見,就必須提供部分 對回溯相容性的影響 並視需要推出發布計畫

建立提取要求

建立提取要求 (PR) 來將文件加入 新增 加入 Markdown 檔案或 PR 的文件連結

盡可能選擇一位待開發客戶審查者。 並將副本寄給其他審查人員如果您沒有選擇待開發客戶審查者,Bazel 維護人員會為您的 PR 指派一位。

建立公關後,審查人員可以在 審查。舉例來說,待開發客戶審查人員可以建議其他評論者,或是 找出遺漏的資訊待開發客戶審查者在核准 PR 時核准 我們認為審查程序可以啟動這不代表提案是完美的 或核准後放送這表示提案所包含的資訊 即可開始討論

發布新提案

傳送公告給 bazel-dev 代表 PR 已提交

您可以複製其他群組 (例如 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」(看起來沒問題) 對提案目前的狀態感到滿意

所有設計審查要求都必須按照這個程序執行。不核准設計 而會影響 Bazel 設計索引

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

您必須自行負責在實作時做出 / 不做決定 以及尚待設計的設計初衷無法順利執行時,則應指明 適當的委派 (將 PR 重新指派給委派代表),或將錯誤重新指派給 Bazel Manager,以便進一步處理

在審查期間

  1. 確保註解和設計反覆程序能繼續執行 建構出建構元件
  2. 核准前,請確認其他審查者的疑慮 均已解決。

所有審查者核准後

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

拒絕設計

  1. 確認 PR 作者會傳送 PR;或是傳送 PR 給他們
  2. PR 會更新文件狀態。
  3. 在文件中新增註解,說明為何該設計無法獲準 以及後續步驟 (例如「重新造訪無效所在地」等) 「假設並重新提交」)。