從以使用者為核心的範本開始
用已驗證的資訊替換所有方括號欄位。移除不適用的章節,不要憑空編造功能。確認支援的升級路徑後,若無須任何升級操作,請明確說明。
# [版本] — [發布日期]
## 重點
- [使用者可見的改善及受益對象]
## 升級
- 起始版本:[支援的舊版本]
- 操作:[必要遷移或無須操作]
- 驗證:[如何確認升級成功]
## 不相容變更
- [行為變更、受影響使用者及遷移連結]
## 修正
- [已解決的問題及 Issue 或 Pull Request 連結]
## 已知問題
- [尚存限制及替代方案]
## 貢獻者
[感謝貢獻者並附上完整變更紀錄連結]把自動產生的說明整理成易讀的解釋
GitHub 可以產生包含已合併 Pull Request、貢獻者及完整變更紀錄連結的版本說明。請把產出當作草稿,檢查版本涵蓋範圍、移除無關項目,並依使用者執行的任務分類變更。
例如,「修正剖析器邊界情況」提供的指引很少。若內容屬實,應解釋最後一欄為空白的 CSV 檔案現在能正確匯入,並連結到修正內容供讀者查閱技術細節。只改了一種情況時,不要宣稱所有剖析問題都已解決。
公告前檢查升級路徑
從支援的舊版本實際嘗試文件記載的升級流程。檢查下載連結,確保文件與版本相符。區分預覽版與穩定版,並讓尚存限制容易找到。
先發布版本資訊,再從社群貼文連結到該頁。公告可著重一項有意義的改善,詳細參考資訊則留在版本說明中。記錄後續問題,並在需要時釐清操作說明。
常見問題
版本說明和變更紀錄一樣嗎?
兩者有重疊。變更紀錄記載隨時間累積的修改;版本說明則解釋特定版本及其對使用者的影響。請互相連結,讓讀者能在概覽和細節之間切換。
可以直接發布自動產生的說明嗎?
請先檢視。自動產生的 Pull Request 標題可能缺少遷移步驟、使用者影響或已知問題。
每個小型程式碼變更都應列入重點嗎?
不用。重點應放在對使用者有意義的變更,詳細技術歷程則保留在連結的變更紀錄中。