---
name: release-notes
description: 根據已合併的變更、PR 或工單清單撰寫給客戶看的版本更新說明（release notes），分成「新功能」「改進」「修正」三類，每一行先講使用者得到的好處，不出現內部術語或工單編號。也會另外寫一份給團隊看的內部變更紀錄（changelog）。有人貼上已合併的 PR、Jira 或 Linear 匯出資料、Sprint 清單，要你寫版本更新說明、changelog、「最新功能」或產品更新時使用。
---

# 版本更新說明

客戶讀版本更新說明只想知道一件事：我現在能做什麼以前做不到的事？每一行都先用客戶的話回答這個問題。客戶看不到的東西就省略，也絕不讓他們去猜工單標題的意思。

## 適用情境

- 版本上線後，手上有已合併的 PR、工單或 commit 訊息清單。
- 要寫「最新功能」頁面、產品內的更新紀錄，或每月的產品更新 Email。
- 團隊還需要一份附工單編號、給客服和業務看的內部變更紀錄。
- 不適用於單一大型功能的上市公告：請用 launch-announcement。

## 需要準備

- 變更清單：PR 標題、工單標題與描述，或 commit 訊息。
- 版本名稱或日期。沒有的話問一次，問不到就寫「[版本日期]」。
- 客戶是誰，才能用他們的說法。不知道的話，就寫給非技術背景的使用者看。
- 選用：新功能的說明文章連結。

## 步驟

1. **刪掉客戶看不到的東西。** 重構、套件版本升級、測試變更、CI、內部工具和日誌記錄，只放進內部版本。沒有可見影響的變更，就不是版本更新說明的內容。
2. **分成新功能、改進、修正。** 新功能＝使用者以前做不到的事。改進＝以前就能做，現在更快、更清楚或範圍更廣。修正＝以前壞掉、現在正常了。工單內容不清楚時，不要用猜的，把它放進內部清單並標上「[待確認：對使用者來說改了什麼？]」。
3. **每一行改寫成先講好處。** 先寫使用者現在能做什麼，再寫怎麼做。寫「在發票頁面把發票匯出成 CSV」，而不是「新增 CSV 匯出 endpoint」。用產品畫面和按鈕上的名稱，不用程式內部的名稱。
4. **修正項目要寫得讓使用者認得出那個錯誤。** 描述他們看到的症狀：「位於亞洲時區的使用者，日期不會再差一天。」不怪罪、也不過度道歉。從來沒影響到客戶的錯誤修正就省略。
5. **依影響程度排序。** 每一類裡最常用或最多人要求的變更放最前面。對使用者來說是同一個變更的多張工單，合併成一行。
6. **控制長度。** 每個變更一行，50 字以內（這個技能的預設值；一般建議是一到兩句）。只有在某個變更是這次版本的重點時，才加一句開場。新功能需要設定時，附上說明文章連結。
7. **寫內部版本。** 使用 Keep a Changelog 的分類：Added、Changed、Deprecated、Removed、Fixed、Security，最新的版本放最前面並附日期。加上工單編號、一個放不可見工作的「內部」分類，以及客服需要知道的事（行為改變、已知問題、移轉步驟）。

## 輸出格式

```markdown
## [版本名稱或日期]

[選用：1 句話說明最大的變更。]

### 新功能
- [使用者現在能做什麼，在哪裡做。] [需要設定時附連結]

### 改進
- [用使用者的話說明什麼變好了。]

### 修正
- [使用者看到的症狀，現在已修正。]

---

## 內部變更紀錄 — [版本名稱或日期]

### Added（新增）
- [白話說明]（[工單編號]，[負責人]）

### Changed（變更）
- [白話說明]（[工單編號]）

### Deprecated / Removed（即將停用／已移除）
- [白話說明，沒有就刪除本段]（[工單編號]）

### Fixed（修正）
- [白話說明]（[工單編號]）

### Security（資安）
- [白話說明，沒有就刪除本段]（[工單編號]）

### 內部
- [重構、套件更新、工具]（[工單編號]）

### 客服需要知道
- [行為改變、已知問題，或「無」]
```

## 範例

**輸入：**

> LIN-412 發票列表新增 CSV 匯出
> LIN-418 修正到期日選擇器的時區偏移錯誤（UTC+8 以東）
> LIN-420 stripe-node 升級到 14.2
> LIN-421 發票列表每頁從 20 筆改為 50 筆
> LIN-425 重構 PDF 產生器
> LIN-426 催款提醒信：主旨加上客戶的公司名稱

**輸出：**

```markdown
## 3月12日版本更新

### 新功能
- 在發票頁面就能把發票匯出成 CSV 檔，直接用試算表開啟或交給會計師。

### 改進
- 發票頁面現在一次顯示 50 張發票，不用一直往下捲。
- 催款提醒信的主旨現在會帶上您客戶的公司名稱，在收件匣裡更顯眼。

### 修正
- 位於亞洲和澳洲時區的使用者，到期日不會再往前跑一天。

---

## 內部變更紀錄 — 3月12日

### Added（新增）
- 發票列表的 CSV 匯出（LIN-412）

### Changed（變更）
- 發票列表每頁筆數由 20 改為 50（LIN-421）
- 提醒信主旨加入客戶公司名稱（LIN-426）

### Fixed（修正）
- 到期日選擇器在 UTC+8 以東的時區偏移（LIN-418）

### 內部
- stripe-node 14.2（LIN-420）
- PDF 產生器重構（LIN-425）

### 客服需要知道
- 依主旨篩選提醒信的客戶，可能需要更新篩選條件（LIN-426）。
```

## 寄出前檢查

- [ ] 給客戶的部分沒有工單編號、程式內部名稱，也沒有「endpoint」「重構」「升級套件」這類字眼。
- [ ] 每一行都以使用者能做的事或會注意到的變化開頭。
- [ ] 每個變更只出現在一個分類中。
- [ ] 沒有描述超出工單內容的變更；不清楚的在內部清單標上「[待確認：……]」。
- [ ] 每一行都在 50 字以內。

## 常見錯誤

- 照抄工單標題、只稍微改幾個字。「修正時區偏移錯誤」對客戶毫無意義；要描述症狀。
- 為了讓版本看起來很豐富而列出不可見的工作。那會把大家在意的變更淹沒。
- 在版本更新說明裡預告接下來的功能。只寫已經上線的東西。