11.1.4 发布公告：变更日志与升级指南

一句话破题

CHANGELOG（变更日志）记录每个版本的变更内容，帮助用户了解更新了什么、是否需要升级、升级时需要注意什么。

核心价值

维护 CHANGELOG 能让你：

• 让用户快速了解版本变化
• 降低升级时的不确定性
• 建立可追溯的项目历史

CHANGELOG 格式规范

遵循 Keep a Changelog 规范：

# Changelog

## [Unreleased]
### Added
- 新增用户头像上传功能

## [1.2.0] - 2024-01-15
### Added
- 新增深色模式支持
- 新增多语言切换功能

### Changed
- 优化首页加载速度

### Fixed
- 修复登录页面样式问题

### Deprecated
- `getUserInfo` API 将在 2.0.0 版本移除

### Removed
- 移除废弃的 `oldApi` 端点

### Security
- 修复 XSS 安全漏洞

## [1.1.0] - 2024-01-01
### Added
- 初始版本发布

变更类型说明

类型	说明	示例
Added	新增功能	新增用户注册功能
Changed	功能变更	优化搜索算法
Deprecated	即将废弃	该 API 将在下版本移除
Removed	已移除	移除旧版登录接口
Fixed	Bug 修复	修复日期显示错误
Security	安全相关	修复权限绕过漏洞

快速上手

手动维护

每次提交时同步更新 CHANGELOG.md：

# 在 Unreleased 区域添加变更
echo "- 新增 XX 功能" >> CHANGELOG.md
git add CHANGELOG.md
git commit -m "docs: update changelog"

自动生成

使用工具从 Git 提交记录生成：

# 安装 conventional-changelog-cli
npm install -g conventional-changelog-cli

# 生成 CHANGELOG
conventional-changelog -p angular -i CHANGELOG.md -s

配合 npm version 使用

{
  "scripts": {
    "version": "conventional-changelog -p angular -i CHANGELOG.md -s && git add CHANGELOG.md"
  }
}

这样每次执行 npm version 时会自动更新 CHANGELOG。

升级指南

对于破坏性变更，需要提供详细的升级指南：

## 从 1.x 升级到 2.0

### 破坏性变更

#### 1. API 响应格式变更

**旧格式**:
```json
{ "data": [...], "total": 100 }

新格式:

{ "items": [...], "pagination": { "total": 100 } }

迁移方法:

// 旧代码
const { data, total } = response

// 新代码
const { items, pagination } = response
const { total } = pagination

2. 环境变量重命名

旧名称	新名称
DB_URL	DATABASE_URL
API_KEY	NEXT_PUBLIC_API_KEY

## GitHub Release

除了 CHANGELOG，还可以在 GitHub 创建 Release：

```bash
# 使用 gh CLI 创建 Release
gh release create v1.2.0 \
  --title "v1.2.0" \
  --notes-file CHANGELOG.md \
  --latest

避坑指南

新手最容易犯的错

1. 只在发布时才更新 CHANGELOG（应该随代码一起提交）
2. 变更描述太笼统（"修复了一些问题"没有价值）
3. 破坏性变更没有迁移指南
4. 忘记更新 Unreleased 区域