變更日誌產生器
自動從 git 歷史記錄產生人類友善的變更日誌。遵循 Keep a Changelog 格式,將提交訊息潤飾成使用者友善的語言,並可選擇建立 GitHub Release。
輸入解析
主要輸入為 git ref 範圍。解析提供的引數:
- 包含
...或..-> git ref 範圍(例如v1.0.0...v1.1.0) - 符合單一標籤/ref -> 從該 ref 到 HEAD
- 符合 GitHub URL 或
#\d+模式 -> PR(僅從該 PR 提取變更)。對於單一 PR 輸入:閱讀 PR 的差異和描述,分類變更,使用 PR 標題作為條目。跳過版本標題。詢問使用者要將這些條目附加到現有變更日誌版本,還是建立新版本。 - 無引數 -> 詢問:「變更日誌應涵蓋哪個範圍?您可以提供 git ref 範圍(例如 v1.0.0...v1.1.0)、標籤(該標籤以來的變更)或 PR 編號。」
處理流程
digraph changelog {
rankdir=TB;
"Resolve input" [shape=box];
"Phase 1: Gather" [shape=box];
"Phase 2: Categorize" [shape=box];
"Phase 3: Polish" [shape=box];
"Phase 4: Review" [shape=box];
"Approved?" [shape=diamond];
"Phase 5: Output" [shape=box];
"Resolve input" -> "Phase 1: Gather";
"Phase 1: Gather" -> "Phase 2: Categorize";
"Phase 2: Categorize" -> "Phase 3: Polish";
"Phase 3: Polish" -> "Phase 4: Review";
"Phase 4: Review" -> "Approved?";
"Approved?" -> "Phase 3: Polish" [label="修訂"];
"Approved?" -> "Phase 5: Output" [label="是"];
}
請勿跳過任何階段。 以自然節奏提問。若使用者一次回答多個問題,接受捆綁答案並跳過。
若使用者說「直接選預設值」或類似語句,選取合理的預設值,說明您的選擇,並請求一次確認。
第一階段:收集
步驟 1 - 收集提交和 PR
在兩個 ref 之間執行 git log 以收集所有提交。如果儲存庫使用 PR,也請使用 gh pr list --state merged 檢查範圍內已合併的 PR。
針對每個提交/PR,提取:
- 提交訊息(主旨 + 內文)
- 變更的檔案(以判斷影響範圍)
- PR 標題與描述(如有)
- 任何 conventional commit 類型前綴(feat, fix, chore 等)
步驟 2 - 閱讀更廣泛的產品背景
閱讀(如果存在):README、package.json(或同等檔案)。目標:了解產品內容,以便撰寫使用者友善的描述。
如果找不到任何內容,詢問:「可以簡短描述一下這個產品嗎?我需要一些背景資訊才能寫出使用者友善的變更日誌條目。」
步驟 3 - 偵測現有格式
檢查儲存庫是否有現有的 CHANGELOG.md。如果存在:
- 偵測格式(Keep a Changelog、自訂等)
- 偵測是否使用表情符號標籤(例如用於新功能、錯誤修正的表情符號)還是純文字類別
- 比對現有風格
如果不存在變更日誌:
- 預設使用 Keep a Changelog 格式
- 詢問:「找不到現有變更日誌。您偏好使用表情符號標籤(例如用於新功能、錯誤修正)還是純文字類別(Added、Fixed 等)?」
第二階段:分類
將所有變更歸類到 Keep a Changelog 類別中。重大變更 會在最上方有專屬區段:
- 重大變更 - 任何會破壞現有行為、API,或需要使用者採取升級動作的變更。為每個變更包含遷移說明。從
feat!:,fix!:,BREAKING CHANGE:頁尾,或差異中移除/重新命名的 API 來偵測。 - 新增 - 新功能
- 變更 - 現有功能的變更
- 即將廢棄 - 將被移除的功能
- 移除 - 被移除的功能
- 修正 - 錯誤修正
- 安全性 - 漏洞修復
分類規則:
- 如果提交遵循 conventional commits(
feat:,fix:等),使用類型進行分類 - 如果不遵循,分析差異和提交訊息以確定類別
- 跳過僅限內部的變更(重構、測試新增、CI 變更、相依性提升),除非它們影響使用者可見的行為
- 不確定某項變更是否為使用者可見時,將其包含在內,讓使用者在審查時移除
- 對於包含 50 個以上提交的範圍,將相關變更分組為更高層級的條目(例如,不列出 12 個個別的 API 修正,而是寫「改善了多個端點的 API 錯誤處理」)。呈現分組版本,讓使用者可以展開任何群組以取得詳細資訊。
呈現分類清單:
「這是我在這個範圍內找到的內容:」
新增 (3)
- 功能 A
- 功能 B
- 功能 C
修正 (2)
- 錯誤修正 A
- 錯誤修正 B
「有任何要新增、移除或重新分類的項目嗎?」
在使用者確認之前,請勿繼續。
第三階段:潤飾
將每個條目重寫為人類友善的語言:
- 以使用者效益為先,而非實作細節
- 「報表載入速度提升 3 倍」而非「最佳化了報表模組的 SQL 查詢執行計畫」
- 「您現在可以將報表匯出為 PDF」而非「新增了報表服務的 PDF 匯出功能」
- 每個條目維持一行(複雜變更最多兩行)
- 在可行時包含 PR/issue 參考(例如
(#123))
版本標題
格式:## [版本] - YYYY-MM-DD
如果範圍的上限是版本標籤(例如 v1.2.0),則使用該版本。如果上限是 HEAD 或分支名稱,詢問:「此變更日誌應使用哪個版本號?」
使用範圍中最新的提交日期,格式為 ISO(YYYY-MM-DD)。
技術附錄
在使用者友善的變更日誌產生後,詢問:
「您是否也希望我產生一份包含實作細節的技術附錄?(適用於開發者導向的文件)」
如果是,則產生更詳細的區段,包含技術細節、重大變更遷移指南和 API 變更。
撰寫規則
- 切勿在產生的內容中使用 em-dashes。不使用「---」字元。請使用逗號、冒號、句號或括號代替。
- 預設使用使用者友善的語言(無術語、無內部功能名稱)
- 每個條目一行,複雜變更最多兩行
- 一致的動詞時態(過去式:「Added」、「Fixed」、「Removed」)
- 在可行時包含 PR/issue 參考
第四階段:審查
呈現完整的變更日誌條目:
「這是變更日誌:」
## [1.2.0] - 2026-04-11 ### Added - 您現在可以將報表匯出為 PDF (#123) ### Fixed - 儀表板不再在頁面載入時閃爍 (#456)「需要任何變更嗎?」
等待核准。僅在使用者確認後才繼續輸出。
第五階段:輸出
CHANGELOG.md
偵測儲存庫根目錄中的現有 CHANGELOG.md。如果找到,讀取整個檔案,識別插入點(在第一個 ## [ 行之前),向使用者呈現建議的插入點,並在寫入前確認。如果未找到,則建立一個包含標準標頭的檔案:
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/).
始終在寫入前確認:
「我會將此內容前置到
CHANGELOG.md。可以繼續嗎?」
GitHub Release
在儲存變更日誌後,詢問:
「您是否也希望我使用此變更日誌建立一個 GitHub Release?」
如果是,使用 gh release create <tag> --notes "<changelog content>" 建立 Release。如果 gh 不可用,告知使用者並跳過。
錯誤處理
gh不可用 -> 告知使用者,跳過 PR 豐富化和 GitHub Release,僅依賴 git log- 無效的 ref/標籤 -> 要求使用者驗證
- 範圍內無提交 -> 告知使用者,要求驗證範圍
- 無產品背景 -> 要求使用者描述產品
- 非 conventional commits -> 回退到差異分析以進行分類
此技能不執行的事項
- 管理版本策略(語意化版本決策由使用者決定)
- 發布至套件註冊表
- 產生部落格文章或電子報(請使用
/blog-post或/newsletter) - 處理分支策略或發行工作流程