changelog-writer

变更日志与发布说明编写器

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

核心工作流

1. 分析提交：解析自上次发布以来的 git 历史
2. 分类变更：按类型分组（feat、fix、docs 等）
3. 识别破坏性变更：标记不兼容的变更
4. 提取亮点：突出最重要的变更
5. 设置文档格式：遵循 Keep a Changelog 格式
6. 建议版本号：建议语义化版本升级
7. 生成发布说明：创建便于用户阅读的摘要

提交分析

从以下内容中提取信息

• 提交消息（最好采用 Conventional Commits 规范）
• PR 标题和描述
• Issue 引用（#123）
• 合并提交消息
• 提交作者

解析模式

feat(auth): add OAuth2 support
^    ^      ^
|    |      └─ Description
|    └─ Scope (optional)
└─ Type

类型对应分类：

• feat → 新增
• fix → 修复
• docs → 文档
• style、refactor → 变更
• perf → 性能
• test → 测试
• chore、ci → 内部
• BREAKING CHANGE → 破坏性变更

变更日志格式（Keep a Changelog）

# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Added

- New feature X
- Support for Y

### Changed

- Updated Z behavior

### Fixed

- Resolved issue #123

## [2.1.0] - 2024-01-15

### Added

- OAuth2 authentication support
- User profile management API
- Dark mode toggle

### Changed

- Improved error messages
- Updated dependencies to latest versions

### Deprecated

- Legacy authentication method (will be removed in 3.0.0)

### Fixed

- Memory leak in WebSocket connection
- Incorrect date formatting in reports
- Race condition in concurrent requests

### Security

- Patched XSS vulnerability in user input

## [2.0.0] - 2023-12-01

### Breaking Changes

- ⚠️ Removed support for Node.js 16
- ⚠️ Changed API response format for `/users` endpoint
- ⚠️ Renamed `config.yaml` to `config.yml`

### Added

- Complete API rewrite with improved performance
- WebSocket support for real-time updates

### Migration Guide

See [MIGRATION_v2.md](./docs/MIGRATION_v2.md) for upgrade instructions.

[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 v2.1.0 - "Feature Release Name"

Released: January 15, 2024

## 🎉 Highlights

This release brings major improvements to authentication and user experience:

- **OAuth2 Support**: Users can now sign in with Google, GitHub, and Microsoft
- **Dark Mode**: Toggle between light and dark themes
- **Performance**: 40% faster API response times

## ✨ New Features

- OAuth2 authentication with popular providers (#456)
- User profile management API (#478)
- Dark mode toggle in settings (#492)
- Export data in CSV format (#501)

## 🐛 Bug Fixes

- Fixed memory leak in WebSocket connections (#489)
- Resolved incorrect date formatting in reports (#495)
- Fixed race condition in concurrent API requests (#503)

## 🔄 Changes

- Improved error messages across the application
- Updated all dependencies to latest stable versions
- Refined UI animations for smoother experience

## 🔒 Security

- Patched XSS vulnerability in user input validation
- Updated JWT library to address CVE-2024-1234

## 📚 Documentation

- Added OAuth2 setup guide
- Updated API reference with new endpoints
- Improved troubleshooting section

## 🙏 Contributors

Thank you to all contributors who made this release possible:

- @alice - OAuth2 implementation
- @bob - Dark mode feature
- @charlie - Bug fixes and testing

## 📦 Installation

```bash
npm install [email protected]
# or
yarn add [email protected]
```

🔗 链接

• 完整变更日志
• 文档
• 迁移指南

---

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

## Semantic Versioning Rules

Given a version number MAJOR.MINOR.PATCH (e.g., 2.1.0):

1. **MAJOR** (2.x.x → 3.x.x)
   - Breaking changes
   - 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 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 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 CHANGE:
• 提交类型带有 !（例如 feat!:）
• PR 标记为“breaking-change”
• 主要依赖项更新
• API 端点变更
• 配置文件格式变更

清晰记录：

### Breaking Changes

⚠️ **API Response Format Changed**

The `/api/users` endpoint now returns:

```json
// Before
{ "data": [...] }

// After
{ "users": [...], "total": 100 }
```

**迁移：**更新 API 客户端，将访问目标从 data 改为 users。

## Automation Tools

### 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

# 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 发布脚本

#!/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')"

面向用户与面向开发者

面向用户（发布说明）

• 重点介绍优势和功能
• 少用技术术语
• 包含截图或演示
• 突出用户体验改进
• 提供升级说明

面向开发者（变更日志）

• 技术细节
• API 变更
• 附带迁移指南的破坏性变更
• 依赖项更新
• 内部重构

按项目类型划分的模板

库/软件包

重点关注：API 变更、破坏性变更、新方法

应用程序

重点关注：新功能、错误修复、UI 改进

CLI 工具

重点关注：新命令、标志变更、行为变更

API 服务

重点关注：端点变更、性能、安全性

最佳实践

1. 描述具体：“修复登录错误” → “修复移动设备上的会话超时问题”
2. 链接 Issue：引用 GitHub Issue（#123）
3. 致谢贡献者：认可他们的工作
4. 突出影响：清晰标记破坏性变更
5. 合理分组：按类型而非时间顺序分组
6. 定期更新：每次发布时更新
7. 遵循规范：采用 Keep a Changelog 格式
8. 遵循语义化版本规范：正确使用

变更日志条目示例

优秀示例

### Added

- OAuth2 authentication support (#456) - @alice
- Export data in CSV format with custom column selection (#501)

### Fixed

- Resolved memory leak in WebSocket connections affecting long-running sessions (#489)
- Fixed race condition in concurrent API requests that caused data inconsistency (#503)

不佳示例

### Added

- Added stuff
- New feature

### Fixed

- Fixed bug
- Updates

版本建议算法

If breaking changes detected:
  MAJOR++, MINOR=0, PATCH=0
Else if new features:
  MINOR++, PATCH=0
Else if only fixes:
  PATCH++

发布检查清单

发布前：

• 检查自上次发布以来的所有提交
• 识别破坏性变更
• 正确分类变更
• 更新 CHANGELOG.md
• 撰写发布说明
• 更新 package.json/pyproject.toml 中的版本号
• 创建 git 标签
• 推送标签以触发 CI/CD
• 发布到软件包注册表（npm、PyPI 等）
• 创建附带说明的 GitHub 发布版本
• 在相关渠道发布公告

输出检查清单

每次生成变更日志都应提供：

• 遵循 Keep a Changelog 格式的 CHANGELOG.md
• 发布说明草稿（便于用户阅读）
• 语义化版本建议（X.Y.Z）
• 清晰标记破坏性变更
• 针对破坏性变更的迁移指南
• 要运行的 git 标签命令
• 比较视图链接