撰寫版本資訊

回報問題 查看原始碼 Nightly · 7.4 . 7.3 7.2 7.1 7.0 6.5

本文件的目標為 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) 存放區