Community寫作與編輯github.com

changelog

根據 Git 歷史記錄自動建立或更新變更日誌(Changelog),按版本分組並依功能類型分類。

changelog 是什麼?

此技能可自動從 Git 歷史記錄產生結構化的變更日誌,將其分組為版本,並根據關鍵字(如 Add、Fix、Performance)對提交進行分類。它支援兩種目標受眾:使用者(產出 `Changelog.md`,著重描述效益)和開發者(產出 `Changelog-Dev.md`,包含提交哈希與 PR 編號)。工作流程會檢查現有日誌、收集 Git 資料、分類提交,並將變更對應到三個階段:開發中 (🔮)、Insiders (🧪) 和 Stable (✅)。它可與 Claude Code、Codex 和 OpenClaw 搭配使用,並透過 `/changelog` 等命令觸發。

相容平台✓Claude Code✓Codex CLI~Cursor
npx skills add processcube-io/ProcessCube.Agent.Skills

Installed? Explore more 寫作與編輯 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

技能:changelog

從 Git 歷史記錄建立或更新變更日誌,按版本分組並依功能類型分類。

觸發條件

  • /changelog - 建立或更新變更日誌
  • "建立變更日誌", "更新變更日誌", "從上次之後有什麼變更…"

參數

如果未提供,請向使用者詢問以下資訊:

  1. 目標受眾(同時決定預設檔案)

    • 使用者 → Changelog.md(簡化,描述效益)
    • 開發者 → Changelog-Dev.md(技術性,含提交詳細資訊)
  2. 模式

    • 更新(預設):僅新增自上次記錄以來的變更
    • 建立新檔:從某個時間點建立完整的變更日誌
  3. 時間範圍(僅用於"建立新檔")

    • 範例:"從 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. 更新變更日誌

更新時:

  1. 讀取現有檔案
  2. 使用新提交更新「開發中」區段
  3. 新版本發佈時:將「開發中」移至「Insiders」或「Insiders」移至「Stable」
  4. 儲存檔案

建立新檔時:

  1. 建立包含所有版本的完整範本

預設檔案

目標受眾檔案內容
使用者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:更新變更日誌(預設)

使用者: "更新變更日誌"

步驟:

  1. 檢查 Changelog.md 是否存在
  2. 找出最後記錄的版本或提交
  3. git log [最後狀態]..HEAD --pretty=format:"%h %ad %s" --date=short
  4. 分類新提交
  5. 更新「開發中」區段

範例 2:為開發者建立變更日誌

使用者: "建立開發者變更日誌"

步驟:

  1. 檢查 Changelog-Dev.md 是否存在
  2. 收集包含提交哈希和 PR 編號的 Git 歷史
  3. 記錄技術細節和重大變更
  4. 儲存至 Changelog-Dev.md

範例 3:記錄新版本

使用者: "我們已經發佈了 v2.4.0-insiders.3"

步驟:

  1. 讀取 Changelog.md
  2. 將「開發中」的內容移至「Insiders v2.4.0-insiders.3」
  3. 建立新的空白「開發中」區段
  4. 加上日期

提示

  • 對於較長的提交訊息,使用第一句
  • PR 編號 (#123) 僅保留在開發者變更日誌中
  • 將相關的提交分組(例如,同一個功能的多個提交)
  • 當提交數量較多時,使用 head 命令限制輸出
  • 更新時始終以現有變更日誌為基礎

相關技能