本文件的目標為 Bazel 協作者。
Bazel 中的修訂版本說明包含 RELNOTES:
標記,後面接著是版本附註。Bazel 團隊會使用這項資訊追蹤每個版本的變更並寫入
發布公告
總覽
變更的內容是否經過錯誤修正?在這種情況下,您不需要提供版本資訊。請附上 GitHub 問題的參照資料。
如果變更以使用者可見的方式新增 / 移除 / 變更 Bazel, 提及這些技術可提高成效
如果變更幅度相當大,請先遵循設計文件政策。
指南規範
我們的使用者會閱讀發布說明,因此請簡短扼要 (最好是用一句話表達),避免使用專業術語 (Bazel 內部術語),並著重於變更內容。
請附上相關說明文件的連結。絕大多數的版本資訊 包含連結如果說明中提及標記、特徵、指令名稱 使用者會想進一步瞭解
在程式碼、符號、旗標或包含 底線。
不要直接複製並貼上錯誤說明。它們通常隱密,而且只有 留下深刻印象 讓他們抓到頭版本說明旨在以使用者能理解的語言,說明變更內容和變更原因。
請一律使用現在式,並使用「Bazel 現已支援 Y」或「X 現已執行 Z」的格式。我們不希望版本資訊看起來像錯誤項目一樣。所有版本 「記事」項目應傳達豐富的資訊,並使用一致的風格和語言
如果項目已淘汰或移除,請使用「X 已淘汰」或「X」 已經移除。」不要使用「已移除」或「已移除」。
如果 Bazel 現在執行不同行為,請使用「X now $newBehavior」,而不要使用 $oldBehavior與時俱進這可讓使用者詳細瞭解使用新版本時的預期結果。
如果 Bazel 目前支援或不再支援某項功能,請使用「Bazel 目前支援/不再支援 X」的格式。
說明為何移除/淘汰/變更某些內容。其中一個句子是 但我們希望使用者能夠評估 建構版本的影響
但「請勿」對日後的功能做出任何承諾。請避免使用 已移除」或「這會改變」這會導致不確定性。使用者首先會想知道「何時?」,我們不希望他們開始擔心目前的版本會在某個未知的時間發生問題。
程序
在發布程序中,我們會收集每個提交的 RELNOTES
標記。我們會將 Google
文件
以審查、編輯和整理筆記
發布管理員會傳送電子郵件給 bazel-dev 郵寄清單。Bazel 協作者受邀參與文件 公告中已正確反映變更內容
稍後,系統會將公告提交至 Bazel 網誌 (使用 bazel-blog) 存放區