更新日志与发布说明编写器 (Changelog & Release Notes Writer)

从版本控制历史生成专业的更新日志和发布说明。

核心工作流 (Core Workflow)

1. 分析提交 (Analyze commits)：解析自上次发布以来的 Git 历史
2. 分类更改 (Categorize changes)：按类型分组（功能、修复、文档等）
3. 识别破坏性更改 (Identify breaking changes)：标记不兼容的更改
4. 提取亮点 (Extract highlights)：提炼最重要的更改
5. 格式化文档 (Format document)：遵循 Keep a Changelog 格式
6. 建议版本 (Suggest version)：推荐语义化版本号升级
7. 生成发布说明 (Generate release notes)：创建用户友好的摘要

提交分析 (Commit Analysis)

从以下来源提取信息 (Extract Information From)

• 提交信息（最好是约定式提交）(Commit messages – preferably conventional commits)
• 拉取请求标题和描述 (PR titles and descriptions)
• 问题引用 (#123) (Issue references)
• 合并提交信息 (Merge commit messages)
• 提交作者 (Commit authors)

解析模式 (Parse Patterns)

feat(auth): 添加 OAuth2 支持 (add OAuth2 support)
^    ^      ^
|    |      └─ 描述 (Description)
|    └─ 范围（可选）(Scope - optional)
└─ 类型 (Type)

类型到类别的映射 (Types to Categories):

• feat → 新增 (Added)
• fix → 修复 (Fixed)
• docs → 文档 (Documentation)
• style, refactor → 变更 (Changed)
• perf → 性能 (Performance)
• test → 测试 (Testing)
• chore, ci → 内部 (Internal)
• BREAKING CHANGE → 破坏性变更 (Breaking Changes)

更新日志格式（Keep a Changelog）(Changelog Format – Keep a Changelog)

# 更新日志 (Changelog)

此项目的所有显著更改都将记录在此文件中。
(All notable changes to this project will be documented in this file.)

格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)，
并且本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/spec/v2.0.0.html)。

## [未发布 (Unreleased)]

### 新增 (Added)

- 新功能 X (New feature X)
- 对 Y 的支持 (Support for Y)

### 变更 (Changed)

- 更新了 Z 的行为 (Updated Z behavior)

### 修复 (Fixed)

- 解决了问题 #123 (Resolved issue #123)

## [2.1.0] - 2024-01-15

### 新增 (Added)

- OAuth2 认证支持 (OAuth2 authentication support)
- 用户资料管理 API (User profile management API)
- 深色模式切换 (Dark mode toggle)

### 变更 (Changed)

- 改进了错误消息 (Improved error messages)
- 将依赖项更新到最新版本 (Updated dependencies to latest versions)

### 弃用 (Deprecated)

- 旧版认证方法（将在 3.0.0 中移除）(Legacy authentication method - will be removed in 3.0.0)

### 修复 (Fixed)

- WebSocket 连接中的内存泄漏 (Memory leak in WebSocket connection)
- 报告中错误的日期格式化 (Incorrect date formatting in reports)
- 并发请求中的竞态条件 (Race condition in concurrent requests)

### 安全 (Security)

- 修补了用户输入中的 XSS 漏洞 (Patched XSS vulnerability in user input)

## [2.0.0] - 2023-12-01

### 破坏性变更 (Breaking Changes)

- ⚠️ 移除了对 Node.js 16 的支持 (Removed support for Node.js 16)
- ⚠️ 更改了 `/users` 端点的 API 响应格式 (Changed API response format for `/users` endpoint)
- ⚠️ 将 `config.yaml` 重命名为 `config.yml` (Renamed `config.yaml` to `config.yml`)

### 新增 (Added)

- 完全重写了 API，性能得到提升 (Complete API rewrite with improved performance)
- 对实时更新的 WebSocket 支持 (WebSocket support for real-time updates)

### 迁移指南 (Migration Guide)

升级说明请参阅 [MIGRATION_v2.md](./docs/MIGRATION_v2.md)。

[unreleased]: https://github.com/user/project/compare/v2.1.0...HEAD
[2.1.0]: https://github.com/user/project/compare/v2.0.0...v2.1.0
[2.0.0]: https://github.com/user/project/releases/tag/v2.0.0

发布说明格式 (Release Notes Format)

# 发布 v2.1.0 - “功能发布名称” (Release v2.1.0 - "Feature Release Name")

发布日期：2024 年 1 月 15 日 (Released: January 15, 2024)

## 🎉 亮点 (Highlights)

此版本在认证和用户体验方面带来了重大改进：
(This release brings major improvements to authentication and user experience:)

- **OAuth2 支持 (OAuth2 Support)**：用户现在可以使用 Google、GitHub 和 Microsoft 登录
- **深色模式 (Dark Mode)**：在浅色和深色主题之间切换
- **性能 (Performance)**：API 响应时间提升 40% (40% faster API response times)

## ✨ 新功能 (New Features)

- 与主流提供商集成的 OAuth2 认证 (#456) (OAuth2 authentication with popular providers)
- 用户资料管理 API (#478) (User profile management API)
- 设置中的深色模式切换 (#492) (Dark mode toggle in settings)
- CSV 格式数据导出 (#501) (Export data in CSV format)

## 🐛 Bug 修复 (Bug Fixes)

- 修复了 WebSocket 连接中的内存泄漏 (#489) (Fixed memory leak in WebSocket connections)
- 解决了报告中日期格式错误的问题 (#495) (Resolved incorrect date formatting in reports)
- 修复了并发 API 请求中的竞态条件 (#503) (Fixed race condition in concurrent API requests)

## 🔄 变更 (Changes)

- 改进了整个应用程序的错误消息 (Improved error messages across the application)
- 将所有依赖项更新到最新的稳定版本 (Updated all dependencies to latest stable versions)
- 优化了 UI 动画，带来更流畅的体验 (Refined UI animations for smoother experience)

## 🔒 安全 (Security)

- 修补了用户输入验证中的 XSS 漏洞 (Patched XSS vulnerability in user input validation)
- 更新了 JWT 库以解决 CVE-2024-1234 (Updated JWT library to address CVE-2024-1234)

## 📚 文档 (Documentation)

- 添加了 OAuth2 设置指南 (Added OAuth2 setup guide)
- 使用新端点更新了 API 参考 (Updated API reference with new endpoints)
- 改进了故障排除部分 (Improved troubleshooting section)

## 🙏 贡献者 (Contributors)

感谢所有为本次发布做出贡献的开发者：
(Thank you to all contributors who made this release possible:)

- @alice - OAuth2 实现 (OAuth2 implementation)
- @bob - 深色模式功能 (Dark mode feature)
- @charlie - Bug 修复和测试 (Bug fixes and testing)

## 📦 安装 (Installation)

```bash
npm install project-name@2.1.0
# 或者 (or)
yarn add project-name@2.1.0
```

🔗 链接 (Links)

• 完整更新日志 (Full Changelog)
• 文档 (Documentation)
• 迁移指南 (Migration Guide)

注意： 这是一个次要版本。没有破坏性更改。可以安全地从 2.0.x 升级。

## 语义化版本规则 (Semantic Versioning Rules)

给定一个版本号 MAJOR.MINOR.PATCH（例如 2.1.0）：
(Given a version number MAJOR.MINOR.PATCH, e.g., 2.1.0:)

1. **MAJOR** (主版本号) (2.x.x → 3.x.x)
   - 破坏性变更 (Breaking changes)
   - 不兼容的 API 更改 (Incompatible API changes)
   - 移除的功能 (Removed features)

2. **MINOR** (次版本号) (2.1.x → 2.2.x)
   - 新功能 (New features)
   - 向后兼容的功能 (Backward-compatible functionality)
   - 弃用的功能 (Deprecated features)

3. **PATCH** (修订号) (2.1.0 → 2.1.1)
   - Bug 修复 (Bug fixes)
   - 安全补丁 (Security patches)
   - 性能改进 (Performance improvements)

**特殊版本 (Special versions):**
- `0.x.x` - 初始开发（次版本中允许破坏性变更）(Initial development - breaking changes allowed in minor)
- `x.y.0-alpha.1` - 预发布版本 (Pre-release)
- `x.y.0-beta.2` - 测试版 (Beta release)
- `x.y.0-rc.1` - 候选发布版 (Release candidate)

## 用于生成更新日志的 Git 命令 (Git Commands for Changelog Generation)

```bash
# 获取自上次标签以来的提交 (Get commits since last tag)
git log $(git describe --tags --abbrev=0)..HEAD --oneline

# 获取两个标签之间的提交 (Get commits between two tags)
git log v2.0.0..v2.1.0 --oneline

# 获取带有拉取请求编号的提交 (Get commits with PR numbers)
git log --merges --pretty=format:"%s" v2.0.0..HEAD

# 获取贡献者 (Get contributors)
git log v2.0.0..HEAD --format='%aN' | sort -u

# 按类型获取提交计数 (Get commit count by type)
git log v2.0.0..HEAD --oneline | grep -E '^[a-f0-9]+ (feat|fix|docs)' | cut -d' ' -f2 | sort | uniq -c

破坏性变更检测 (Breaking Changes Detection)

查找以下指标 (Look for these indicators)：

• 提交信息包含 BREAKING CHANGE: (Commit message contains BREAKING CHANGE:)
• 提交类型带有 !（例如 feat!:）(Commit type has ! – e.g., feat!:)
• 拉取请求标记为“破坏性变更”(breaking-change) (PR labeled with “breaking-change”)
• 主要依赖更新 (Major dependency updates)
• API 端点更改 (API endpoint changes)
• 配置文件格式更改 (Config file format changes)

清晰记录 (Document clearly):

### 破坏性变更 (Breaking Changes)

⚠️ **API 响应格式已更改 (API Response Format Changed)**

`/api/users` 端点现在返回：
(The `/api/users` endpoint now returns:)

```json
// 之前 (Before)
{ "data": [...] }

// 之后 (After)
{ "users": [...], "total": 100 }
```

迁移 (Migration): 更新你的 API 客户端，访问 users 而不是 data。

## 自动化工具 (Automation Tools)

### 使用 conventional-changelog (Using conventional-changelog)
```bash
npm install -g conventional-changelog-cli

# 生成更新日志 (Generate changelog)
conventional-changelog -p angular -i CHANGELOG.md -s

# 为特定版本生成 (Generate for specific version)
conventional-changelog -p angular -i CHANGELOG.md -s -r 0

使用 git-cliff (Using git-cliff)

# 安装 git-cliff (Install git-cliff)
cargo install git-cliff

# 生成更新日志 (Generate changelog)
git-cliff --tag v2.1.0 > CHANGELOG.md

# 生成发布说明 (Generate release notes)
git-cliff --tag v2.1.0 --unreleased

GitHub 发布脚本 (GitHub Release Script)

#!/bin/bash
# scripts/release.sh

VERSION=$1
PREVIOUS_TAG=$(git describe --tags --abbrev=0)

# 生成发布说明 (Generate release notes)
gh release create "$VERSION" \
  --title "Release $VERSION" \
  --notes "$(git log $PREVIOUS_TAG..HEAD --pretty=format:'- %s')"

面向用户 vs 面向开发者 (User-Facing vs Developer-Facing)

面向用户（发布说明）(User-Facing – Release Notes)

• 关注收益和功能 (Focus on benefits and features)
• 减少技术术语 (Less technical jargon)
• 包含截图/演示 (Include screenshots/demos)
• 突出用户体验改进 (Highlight user experience improvements)
• 提供升级说明 (Provide upgrade instructions)

面向开发者（更新日志）(Developer-Facing – Changelog)

• 技术细节 (Technical details)
• API 更改 (API changes)
• 带有迁移指南的破坏性变更 (Breaking changes with migration guides)
• 依赖项更新 (Dependencies updates)
• 内部重构 (Internal refactorings)

按项目类型的模板 (Templates by Project Type)

库/包 (Library/Package)

关注：API 更改、破坏性变更、新方法 (Focus on: API changes, breaking changes, new methods)

应用程序 (Application)

关注：新功能、Bug 修复、UI 改进 (Focus on: New features, bug fixes, UI improvements)

命令行工具 (CLI Tool)

关注：新命令、标志更改、行为更改 (Focus on: New commands, flag changes, behavior changes)

API 服务 (API Service)

关注：端点更改、性能、安全 (Focus on: Endpoint changes, performance, security)

最佳实践 (Best Practices)

1. 具体明确 (Be specific)：“修复了登录错误” → “修复了移动端的会话超时问题”
2. 链接问题 (Link issues)：引用 GitHub 问题 (#123) (Reference GitHub issues)
3. 感谢贡献者 (Credit contributors)：认可工作 (Acknowledge work)
4. 突出影响 (Highlight impact)：清晰标记破坏性变更 (Mark breaking changes clearly)
5. 逻辑分组 (Group logically)：按类型分组，而不是按时间 (By type, not chronologically)
6. 定期更新 (Update regularly)：每次发布时更新 (With each release)
7. 遵循约定 (Follow conventions)：Keep a Changelog 格式
8. 语义化版本 (Semantic versioning)：正确使用 (Use correctly)

更新日志条目示例 (Changelog Entry Examples)

好的示例 (Good Examples)

### 新增 (Added)

- OAuth2 认证支持 (#456) - @alice (OAuth2 authentication support)
- 支持带有自定义列选择的 CSV 格式数据导出 (#501) (Export data in CSV format with custom column selection)

### 修复 (Fixed)

- 解决了影响长时间运行会话的 WebSocket 连接内存泄漏问题 (#489) (Resolved memory leak in WebSocket connections affecting long-running sessions)
- 修复了导致数据不一致的并发 API 请求竞态条件 (#503) (Fixed race condition in concurrent API requests that caused data inconsistency)

不好的示例 (Bad Examples)

### 新增 (Added)

- 添加了一些东西 (Added stuff)
- 新功能 (New feature)

### 修复 (Fixed)

- 修复了错误 (Fixed bug)
- 更新 (Updates)

版本建议算法 (Version Suggestion Algorithm)

如果检测到破坏性变更 (If breaking changes detected):
  主版本号++，次版本号=0，修订号=0 (MAJOR++, MINOR=0, PATCH=0)
否则如果有新功能 (Else if new features):
  次版本号++，修订号=0 (MINOR++, PATCH=0)
否则如果只有修复 (Else if only fixes):
  修订号++ (PATCH++)

发布检查清单 (Release Checklist)

在发布之前 (Before publishing release)：

• 审查自上次发布以来的所有提交 (Review all commits since last release)
• 识别破坏性变更 (Identify breaking changes)
• 正确分类更改 (Categorize changes properly)
• 更新 CHANGELOG.md (Update CHANGELOG.md)
• 编写发布说明 (Write release notes)
• 更新 package.json/pyproject.toml 中的版本 (Update version in package.json/pyproject.toml)
• 创建 Git 标签 (Create git tag)
• 推送标签以触发 CI/CD (Push tag to trigger CI/CD)
• 发布到包注册表（npm、PyPI 等）(Publish to package registry – npm, PyPI, etc.)
• 使用发布说明创建 GitHub 发布 (Create GitHub release with notes)
• 在相关渠道上宣布 (Announce on relevant channels)

输出检查清单 (Output Checklist)

每次生成更新日志都应提供 (Every changelog generation should provide)：

• 遵循 Keep a Changelog 格式的 CHANGELOG.md 文件
• 发布说明草稿（用户友好）(Release notes draft – user-friendly)
• 语义化版本建议（X.Y.Z）(Semantic version suggestion – X.Y.Z)
• 清晰标记破坏性变更 (Breaking changes clearly marked)
• 针对破坏性变更的迁移指南 (Migration guide for breaking changes)
• 要运行的 Git 标签命令 (Git tag command to run)
• 对比视图的链接 (Links to compare view)