設計文件

如果您打算新增、變更或移除向使用者顯示的功能,或重大架構變更至 Bazel 程式,必須請先設計設計文件,並在提交變更前先進行審查。

以下列舉一些重大異動:

  • 新增或刪除原生版本規則
  • 原生廣告規則重大異動
  • 變更原生建構規則語意的異動,影響單一規則的行為
  • Bazel 規則定義 API 的變更
  • Bazel 用來連線至其他系統的 API 相關異動
  • Starlark 語言、語意或 API 的變更
  • 可能會對 Bazel 效能或記憶體用量造成嚴重影響 (或更嚴重) 的變更
  • 廣泛使用的內部 API 相關異動
  • 旗標和指令列介面有所變更。

設計審查原因

撰寫設計文件時,您可以與其他 Bazel 開發人員協調,並向 Bazel 核心團隊尋求協助。舉例來說,當提案新增、移除或修改 BUILD、WORKSPACE 或 bzl 檔案中提供的任何函式或物件時,請將 Starlark 團隊新增為審查人員。設計文件會在提交前進行審核,原因如下:

  • Bazel 是一項非常複雜的系統;看不見的本機變更可能會造成重大影響。
  • 團隊獲得許多使用者提出的功能要求;這類要求不僅需要針對技術可行性進行評估,同時也要評估其他功能要求的重要性。
  • Bazel 功能通常是由核心團隊以外的使用者實作;這類貢獻者對於 Bazel 專業知識具有相當大的貢獻。
  • Bazel 團隊本身的專業程度不同;沒有一位團隊成員能夠完全瞭解 Bazel 的各個角落。
  • 對 Bazel 的變更必須回溯回溯相容性,並避免破壞變更。

Bazel 的設計審查政策可協助盡可能提高以下情況:

  • 所有功能要求都會獲得一定程度的審查次數。
  • 負責人員的設計上會注重權重,而在投注於困難的實作階段。

為了協助您踏出第一步,請參閱 Bazel 提案存放區中的設計文件。由於設計仍在進行中,因此實作詳細資料可能會隨時間而改變, 已發布的設計文件會呈現初始設計,且「不」隨著設計實際實施而改變。如需 Bazel 功能說明,請一律參閱說明文件。

協作者工作流程

協作者可以提出設計文件、傳送提取要求並要求審核提案者。

撰寫設計文件

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

  • 作家
  • 上次重大變更的日期
  • 評論者清單 (其中只有一位) 主要評論者
  • 目前狀態 (草稿審核中已核准已拒絕已導入/ 1}、已導入)
  • 討論串連結 (在公告之後加入)

這份文件可以編寫成可解讀的 Google 文件,也可以使用 Markdown 編寫。請參閱下文的 Markdown / Google 文件比較

如果提案對使用者俱有影響,就必須撰寫一段區段,解釋對回溯相容性的影響 (如有需要,請採用發布計畫)。

建立提取要求

建立提取要求 (將 PR) 新增至設計索引,藉此分享設計文件。將 Markdown 檔案或文件連結新增至 PR。

請盡可能選擇待開發客戶審查人員,並邀請其他審查人員。如果未選擇待開發客戶審查者,Bazel 維護人員會指派一個給您的 PR。

建立 PR 後,審查人員可以在程式碼審查期間進行初步註解。舉例來說,待開發客戶審查人員可以建議額外的審查人員,或指出缺少的資訊。待開發客戶審查員一旦確認審查程序可開始,就會核准 PR。但這並不代表提案要適中或通過核准這代表提案中包含充足的資訊來展開討論。

宣布新提案

在提交 PR 時傳送公告至 bazel-dev

您可以複製其他群組 (例如 bazel-talk,藉此取得 Bazel 使用者的意見回饋)。

反覆審查

任何人都可以對提案發表留言。試著回答問題、釐清提案並解決疑慮。

討論內容應透過公告討論串進行, 如果提案已進入 Google 文件,則可以改用註解 (請注意,允許使用匿名註解)。

更新狀態

建立新的 PR,在疊代作業完成後更新提案的狀態。將 PR 傳送給另一位待開發客戶審查員,並邀請其他審查人員。

如要正式接受提案,待開發客戶審查人員會在確認其他審查人員同意裁決後,核准 PR。

第一次公告與提案核准至少需要 1 週時間。以確保使用者有充分時間閱讀文件並分享自己的疑慮。

系統會在提案接受前開始導入,例如做為概念驗證或實驗。但在審查完成前,您無法提交變更。

選擇待開發客戶審查者

頭名審查人員必須為符合下列條件的網域專家:

  • 熟悉相關子系統
  • 目的在於提供建設性意見回饋
  • 整個審核期皆適用於該流程

請考慮查看各種團隊標籤的聯絡人資料。

Markdown 和 Google 文件

決定最適合的選項,因為兩者都接受。

使用 Google 文件的好處:

  • 集思廣益,容易上手。
  • 協作編輯。
  • 快速疊代,
  • 輕鬆提出修改建議。

使用 Markdown 檔案的好處:

  • 清理網址。
  • 修訂版本的明確記錄。
  • 公開連結之前,不需再設定存取權限。
  • 使用搜尋引擎即可輕鬆搜尋。
  • 具有前-性:純文字不是任何特定工具的優點,也不需要連上網際網路,
  • 即使作者不在身邊,你還是可以更新這些內容。
  • 而且可以自動處理 (更新/偵測無效連結、擷取作者清單等)。

您可以選擇先對 Google 文件進行疊代,再將其轉換成 Markdown 做為張貼依據。

使用 Google 文件

為保持一致性,請使用 Bazel 設計文件範本。其中包含必要的標頭,並建立與其他 Bazel 相關文件之間的一致性。做法是依序點選 [檔案] > [建立副本],或是點選這個連結,建立設計文件範本的副本{/3 }。

如要向全世界公開您的文件,請按一下 [共用] > [進階] > [變更...],然後選擇 [開啟 -所有知道連結的使用者」。 如果您允許在文件中加註,即使沒有 Google 帳戶,任何人都能以匿名方式加註。

使用 Markdown

文件會儲存在 GitHub 中,並使用 GitHub 的 GitHub 版本版本 (規格)。

建立 PR 以更新現有文件。重大變更應由文件審查人員進行審查。任何變更內容 (例如拼寫錯誤或格式設定) 可由所有人核准。

審查者工作流程

審查人員加註、審查及核准設計文件。

一般審查者責任

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

收到新提案時

  1. 快速查看文件。
  2. 缺少重要資訊,或設計不符合專案目標時,請留言。
  3. 建議其他審查者。
  4. 審核公關準備進行審查。

在審核期間

  1. 與設計作者討論,找出有問題的問題或需要釐清。
  2. 如有需要,請邀請非評論者的意見來討論設計。
  3. 決定要將哪些註解標示為作者需要處理的備註。
  4. 當您對提案的當前狀態感到滿意時,請在討論串中寫入「LGTM」(看起來不錯)。

針對所有設計審查要求,請採用這個程序進行。如果 Bazel 不在設計索引中,也不代表影響 Bazel 的設計。

待開發客戶審查者的責任

您必須負責決定待處理應用程式的實作方式,以及是否採取任何行動。如果您無法這麼做,請找出適當的委派代表 (將 PR 重新指派給委派對象),或將該錯誤重新指派給 Bazel 管理員,以進行進一步處置。

在審核期間

  1. 確保註解和設計疊代程序具有建設性,
  2. 在核准之前,請確保其他審查者提出的疑慮已解決。

所有審查人員皆核准後

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

拒絕設計

  1. 請確認波多黎各的作者能夠傳送公關;或傳送相關要求給對方。
  2. PR 會更新文件狀態。
  3. 在文件中新增註解,說明該設計為何無法通過目前狀態,並簡述後續步驟 (例如「重新審視無效假設並加以重新提交」)。