版本發行說明範本（Release Notes）

參照標準：Keep a Changelog 1.1.0 / SemVer 2.0.0 / ISO/IEC/IEEE 12207:2017（Release Management）
文件用途：正式記錄每個版本的變更內容，供開發、維運、使用者了解版本差異
適用階段：部署上線階段（Deployment Phase）— Release Management

📋 章節目錄

1. 文件資訊
2. 版本摘要
3. 新增功能（Added）
4. 變更項目（Changed）
5. 修復項目（Fixed）
6. 棄用項目（Deprecated）
7. 移除項目（Removed）
8. 安全性修復（Security）
9. 已知問題（Known Issues）
10. 升級指南
11. 相容性說明

1. 文件資訊

📝 範本

📖 使用說明

• 版本號遵循 SemVer 2.0.0：
  • MAJOR：不相容的 API 變更
  • MINOR：向後相容的新功能
  • PATCH：向後相容的 Bug 修復
• 每次正式發佈（含 Hotfix）都需要 Release Notes
• Git Tag 與 Build Number 確保可從 Release Notes 追溯到原始碼

💡 範例

2. 版本摘要

📝 範本

概述

{用 2-3 句話描述本版本的核心主題與重要變更}

重點亮點

• 🎯 {亮點 1}
• 🎯 {亮點 2}
• 🎯 {亮點 3}

影響範圍

📖 使用說明

• 版本摘要讓讀者快速了解「這個版本主要做了什麼」
• 重點亮點不超過 5 項，只列最重要的
• 影響範圍協助不同角色判斷是否需要閱讀詳細內容

💡 範例

概述

v2.1.0 新增薪資計算自動化排程、請假流程行動推播通知，並修復 4 個已知缺陷。效能優化使報表匯出速度提升 40%。

重點亮點

• 🎯 薪資計算支援自動化月結排程（cron-based）
• 🎯 請假審核結果即時推播通知（WebSocket）
• 🎯 報表匯出效能優化（非同步 + 分頁）
• 🎯 安全性更新：JWT Token 改用 RS256 簽章

影響範圍

3. 新增功能（Added）

📝 範本

📖 使用說明

• 列出所有本版新增的功能（使用者可感知的）
• 功能 ID 連結到需求管理工具（如 Azure DevOps Work Item）
• 依優先級或模組排序

💡 範例

4. 變更項目（Changed）

📝 範本

📖 使用說明

• 列出行為變更但非新功能的項目
• 「向後相容」欄位特別重要 — 不相容變更需在升級指南說明
• 常見變更：API 回傳格式調整、預設值變更、流程調整

💡 範例

5. 修復項目（Fixed）

📝 範本

📖 使用說明

• 列出本版修復的所有缺陷
• 嚴重度標示讓使用者判斷是否影響其使用情境
• Critical/High 缺陷建議在描述中加註影響範圍

💡 範例

6. 棄用項目（Deprecated）

📝 範本

📖 使用說明

• 標示未來將移除的功能/API，給使用者遷移時間
• 必須提供替代方案與預計移除版本
• 棄用不代表立即移除，通常保留 2-3 個 Minor 版本

💡 範例

7. 移除項目（Removed）

📝 範本

📖 使用說明

• 列出本版正式移除的功能（之前標示為 Deprecated 的）
• 必須標明最後支援版本，供尚未遷移的使用者參考
• 提供具體遷移指南或連結

💡 範例

8. 安全性修復（Security）

📝 範本

📖 使用說明

• 安全性修復獨立列出，方便資安團隊追蹤
• 揭露程度視情況：內部已修復可詳述；若有公開 CVE 則引用
• 建議所有使用者盡速升級至包含安全修復的版本

💡 範例

9. 已知問題（Known Issues）

📝 範本

📖 使用說明

• 已知問題是此版本存在但尚未修復的限制或缺陷
• 必須提供暫時方案（Workaround）讓使用者應對
• 透明揭露建立使用者信任

💡 範例

10. 升級指南

📝 範本

10.1 前置條件

• {前置條件 1}
• {前置條件 2}

10.2 升級步驟

1. {步驟 1}
2. {步驟 2}
3. {步驟 3}

10.3 資料庫 Migration

-- Migration 名稱：{名稱}
-- 說明：{Migration 描述}
{SQL 示意}

10.4 組態變更

📖 使用說明

• 升級指南提供維運人員明確的升級步驟
• 若為 Minor/Patch 版本且無 Breaking Change，可標註「無需特殊升級步驟」
• 資料庫 Migration 需標示是否可回滾

💡 範例

10.1 前置條件

• 確認目前版本為 v2.0.x（不支援從 v1.x 直接升級）
• 備份資料庫
• 確認 WebSocket 相關 Port (8080) 已開通

10.2 升級步驟

1. 停止排程任務（避免薪資計算衝突）
2. 執行資料庫 Migration：dotnet ef database update
3. 部署新版應用程式 Image：hrms:v2.1.0
4. 部署 Notification WebSocket Service
5. 更新 Kong 路由設定（新增 /ws 路由）
6. 設定薪資計算 CronJob：0 2 25 * *
7. 驗證健康檢查端點

10.3 資料庫 Migration

-- Migration: AddNotificationLogs_20260518
-- 可回滾：是
CREATE TABLE notification_logs (
    id BIGSERIAL PRIMARY KEY,
    employee_id INT NOT NULL REFERENCES employees(id),
    type VARCHAR(50) NOT NULL,
    payload JSONB,
    sent_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    read_at TIMESTAMPTZ
);
CREATE INDEX idx_notification_employee ON notification_logs(employee_id, sent_at DESC);

10.4 組態變更

11. 相容性說明

📝 範本

📖 使用說明

• 明確列出本版本的支援環境與相容性限制
• API 向後相容性對 API 消費者特別重要
• 若有 Breaking Change，需在此明確標示

💡 範例

📌 範本使用注意事項

1. 本範本依據 Keep a Changelog 1.1.0 與 SemVer 2.0.0 精神擴展，結合 ISO/IEC/IEEE 12207:2017 Release Management
2. 每次正式版本發佈（含 Hotfix）必須產出 Release Notes
3. 搭配「CHANGELOG 範本」使用 — CHANGELOG 是累計歷史，Release Notes 是單次詳細說明
4. 搭配「部署指引範本」使用 — 升級指南與部署步驟互補
5. Release Notes 需存放於版本控制中，與對應 Git Tag 關聯