技能:changelog
從 Git 歷史記錄建立或更新變更日誌,按版本分組並依功能類型分類。
觸發條件
/changelog- 建立或更新變更日誌- "建立變更日誌", "更新變更日誌", "從上次之後有什麼變更…"
參數
如果未提供,請向使用者詢問以下資訊:
-
目標受眾(同時決定預設檔案)
- 使用者 →
Changelog.md(簡化,描述效益) - 開發者 →
Changelog-Dev.md(技術性,含提交詳細資訊)
- 使用者 →
-
模式
- 更新(預設):僅新增自上次記錄以來的變更
- 建立新檔:從某個時間點建立完整的變更日誌
-
時間範圍(僅用於"建立新檔")
- 範例:"從 2025 年 3 月起", "從 v2.3.0 起"
工作流程
1. 檢查現有變更日誌
# 檢查變更日誌是否存在
ls Changelog.md Changelog-Dev.md 2>/dev/null
如果變更日誌已存在:
- 找出最後記錄的版本或提交
- 在標記
## 🔮 開發中之後尋找最後已知的提交 - 或者以上一個記錄的 Insiders/Stable 版本作為參考
2. 收集 Git 資料
# 取得帶日期的標籤
git for-each-ref --sort=-creatordate --format='%(refname:short) %(creatordate:short)' refs/tags
# 找出最後一個標籤
git describe --tags --abbrev=0
# 自最後一個標籤以來的提交(用於"開發中")
git log $(git describe --tags --abbrev=0)..HEAD --pretty=format:"%h %ad %s" --date=short
# 自特定版本以來的提交
git log v2.3.0..HEAD --pretty=format:"%h %ad %s" --date=short
3. 分類提交
分析提交訊息並將其歸類:
| 類別 | 關鍵字 |
|---|---|
| 新功能 | Add, Feat, Feature, New, Implement |
| 錯誤修正 | Fix, Bugfix, Hotfix, Resolve |
| 效能 | Performance, Optimize, Speed |
| 技術性 | Bump, Update, Refactor, Chore, Deps |
忽略:
- 合併提交("Merge branch", "Merge pull request")
- 版本提交("Release v", "Bump version")
- WIP 提交、建置修正
4. 對應版本
重要: 功能會依序經歷以下階段:
🔮 開發中 → 🧪 Insiders → ✅ Stable
(展望) (早期使用者) (所有使用者)
- 一個功能只能列在一個階段中
- 如果它已在 Stable 階段,則之前必定在 Insiders 階段
- 如果它已在 Insiders 階段,則之前必定在開發中階段
- 每個區段僅顯示相較於前一版本的新變更
5. 更新變更日誌
更新時:
- 讀取現有檔案
- 使用新提交更新「開發中」區段
- 新版本發佈時:將「開發中」移至「Insiders」或「Insiders」移至「Stable」
- 儲存檔案
建立新檔時:
- 建立包含所有版本的完整範本
預設檔案
| 目標受眾 | 檔案 | 內容 |
|---|---|---|
| 使用者 | Changelog.md | 描述效益,無技術細節,無提交哈希 |
| 開發者 | Changelog-Dev.md | 技術細節、提交哈希、PR 編號、重大變更 |
輸出範本(使用者)
# 變更日誌 [專案名稱]
---
## 🔮 開發中(下一個版本的展望)
*這些功能是在 [最後一個標籤] 之後新增的,將包含在下一個版本中。*
### 新功能
- 從使用者角度描述功能
### 錯誤修正
- 從使用者角度描述修正
---
## 🧪 Insiders vX.Y.Z-insiders.N (DD.MM.YYYY)
*預覽版本,包含相較於 Stable vX.Y.Z 的新功能。*
### 新功能(相較於 vX.Y.Z)
- 功能描述
---
## ✅ Stable vX.Y.Z (DD.MM.YYYY)
*穩定版本 - 包含 vX.Y.Z-insiders.1 到 vX.Y.Z-insiders.N 的所有功能。*
### 新功能(相較於 vX.Y-1.Z)
- 功能描述 *(自 insiders.N 起)*
### 錯誤修正(相較於 vX.Y-1.Z)
- 修正描述 *(自 insiders.M 起)*
---
## 發佈流程
功能在使用者可以使用之前,會經歷三個階段:
🔮 開發中 → 🧪 Insiders → ✅ Stable (展望) (早期使用者) (所有使用者)
| 階段 | 目標受眾 | 描述 |
|-------|------------|--------------|
| 🔮 **開發中** | 開發者 | 即將推出的功能預覽。尚未包含在任何版本中。 |
| 🧪 **Insiders** | 早期使用者 | 用於在 Stable 版本之前測試新功能的預覽版本。 |
| ✅ **Stable** | 所有使用者 | 生產就緒版本。功能已完全測試並核准。 |
**注意:** 每個區段僅列出該階段**新增**的變更。
輸出範本(開發者)
# 變更日誌(開發者)
---
## 🔮 開發中
*自 [最後一個標籤] 以來的提交*
### 新功能
- `abc1234` 新增功能 X (#123)
### 錯誤修正
- `def5678` 修正 Bug Y (#456)
### 技術性變更
- `ghi9012` 更新相依套件 Z
---
## 🧪 Insiders vX.Y.Z-insiders.N (DD.MM.YYYY)
### 重大變更
- 重大變更描述
### 新功能
- `abc1234` 功能描述 (#123)
### 錯誤修正
- `def5678` 修正描述 (#456)
---
## ✅ Stable vX.Y.Z (DD.MM.YYYY)
*包含 Insiders .1 到 .N*
### 重大變更
- 描述
### 提交
- 自上一次 Stable 以來的所有提交列表
範例
範例 1:更新變更日誌(預設)
使用者: "更新變更日誌"
步驟:
- 檢查
Changelog.md是否存在 - 找出最後記錄的版本或提交
git log [最後狀態]..HEAD --pretty=format:"%h %ad %s" --date=short- 分類新提交
- 更新「開發中」區段
範例 2:為開發者建立變更日誌
使用者: "建立開發者變更日誌"
步驟:
- 檢查
Changelog-Dev.md是否存在 - 收集包含提交哈希和 PR 編號的 Git 歷史
- 記錄技術細節和重大變更
- 儲存至
Changelog-Dev.md
範例 3:記錄新版本
使用者: "我們已經發佈了 v2.4.0-insiders.3"
步驟:
- 讀取 Changelog.md
- 將「開發中」的內容移至「Insiders v2.4.0-insiders.3」
- 建立新的空白「開發中」區段
- 加上日期
提示
- 對於較長的提交訊息,使用第一句
- PR 編號 (#123) 僅保留在開發者變更日誌中
- 將相關的提交分組(例如,同一個功能的多個提交)
- 當提交數量較多時,使用
head命令限制輸出 - 更新時始終以現有變更日誌為基礎