專案指南

開源專案的 GitHub 版本說明範本

好的版本說明會告訴使用者是否該升級,以及下一步該做什麼。已合併 Pull Request 的清單是有用的依據,但通常無法完整說明升級體驗。發布前應補充對使用者的影響及必要操作。

GitHubStart 編輯團隊 · 更新日期

從以使用者為核心的範本開始

用已驗證的資訊替換所有方括號欄位。移除不適用的章節,不要憑空編造功能。確認支援的升級路徑後,若無須任何升級操作,請明確說明。

# [版本] — [發布日期]

## 重點
- [使用者可見的改善及受益對象]

## 升級
- 起始版本:[支援的舊版本]
- 操作:[必要遷移或無須操作]
- 驗證:[如何確認升級成功]

## 不相容變更
- [行為變更、受影響使用者及遷移連結]

## 修正
- [已解決的問題及 Issue 或 Pull Request 連結]

## 已知問題
- [尚存限制及替代方案]

## 貢獻者
[感謝貢獻者並附上完整變更紀錄連結]

把自動產生的說明整理成易讀的解釋

GitHub 可以產生包含已合併 Pull Request、貢獻者及完整變更紀錄連結的版本說明。請把產出當作草稿,檢查版本涵蓋範圍、移除無關項目,並依使用者執行的任務分類變更。

例如,「修正剖析器邊界情況」提供的指引很少。若內容屬實,應解釋最後一欄為空白的 CSV 檔案現在能正確匯入,並連結到修正內容供讀者查閱技術細節。只改了一種情況時,不要宣稱所有剖析問題都已解決。

公告前檢查升級路徑

從支援的舊版本實際嘗試文件記載的升級流程。檢查下載連結,確保文件與版本相符。區分預覽版與穩定版,並讓尚存限制容易找到。

先發布版本資訊,再從社群貼文連結到該頁。公告可著重一項有意義的改善,詳細參考資訊則留在版本說明中。記錄後續問題,並在需要時釐清操作說明。

常見問題

版本說明和變更紀錄一樣嗎?

兩者有重疊。變更紀錄記載隨時間累積的修改;版本說明則解釋特定版本及其對使用者的影響。請互相連結,讓讀者能在概覽和細節之間切換。

可以直接發布自動產生的說明嗎?

請先檢視。自動產生的 Pull Request 標題可能缺少遷移步驟、使用者影響或已知問題。

每個小型程式碼變更都應列入重點嗎?

不用。重點應放在對使用者有意義的變更,詳細技術歷程則保留在連結的變更紀錄中。

參考資料