撰寫版本資訊

本文件的目標為 Bazel 協作者。

Bazel 中的修訂說明包括在後面加上版本的 RELNOTES: 標記 。Bazel 團隊會使用這項資訊追蹤每個版本的變更並寫入 發布公告

總覽

• 變更的內容是否經過錯誤修正？在這種情況下，您不需要提供版本資訊。請 附上 GitHub 問題參考資料。

• 如果變更以使用者可見的方式新增 / 移除 / 變更 Bazel， 提及這些技術可提高成效

如果大幅變更，請按照設計文件的指示進行 政策。

指南規範

版本資訊會向使用者顯示，因此應力求簡短 (最好是一篇) 因此請避免使用專業術語 (Bazel-internal 術語)，最好專注於 變更的重點

• 附上相關說明文件的連結。絕大多數的版本資訊 包含連結如果說明中提及標記、特徵、指令名稱 使用者會想進一步瞭解

• 在程式碼、符號、旗標或包含 底線。

• 不要直接複製並貼上錯誤說明。它們通常隱密 留下深刻印象 讓他們抓到頭版本資訊 目的是以容易理解的用語，說明變更的項目與原因。

• 一律使用現在式和格式「Bazel 現在支援 Y」格式或「X 現在 。」我們不希望版本資訊看起來像錯誤項目一樣。所有版本 「記事」項目應傳達豐富的資訊，並使用一致的風格和語言

• 如果項目已淘汰或移除，請使用「X 已淘汰」或「X」 已經移除。」未「已移除」或「已移除」的訊息。

• 如果 Bazel 現在執行不同行為，請使用「X now $newBehavior」，而不要使用 $oldBehavior與時俱進這樣使用者才能清楚知道 瞭解推出新版本的時機

• 如果 Bazel 現在支援或不再支援某項功能，請使用「Bazel 現在支援」 / 不再支援 X」。

• 說明項目遭到移除 / 淘汰 / 變更的原因。其中一個句子是 但我們希望使用者能夠評估 建構版本的影響

• 但「請勿」對日後的功能做出任何承諾。請避免使用 已移除」或「這會改變」導致不確定性。第一項原則 使用者會想知道「何時」我們不希望他們一開始 目前的建構作業在不明時間中斷

程序

隨著版本推出 程序 收集每個修訂版本的 RELNOTES 標記我們會將 Google 文件 以審查、編輯和整理筆記

發布管理員會傳送電子郵件給 bazel-dev 郵寄清單。 Bazel 協作者受邀參與文件 公告中已正確反映變更內容

稍後，系統會將公告提交至 Bazel 網誌 (使用 bazel-blog) 存放區