---
description: 生成 changelog、更新 SYS_VERSION、打 tag 并推到远端
---

发布一个新版本，遵循以下既定流程，**严格按顺序执行**，不要省略或调整步骤。

## 步骤

### 1. 生成 changelog 与版本号

执行：

```bash
bash update_changelog.sh
```

脚本会：
- 在 `changelog.md` 顶部写入 `## 3.1.YYYYMMDDHH`，并附上自上一个 tag 起的 feat / fix / other 提交。
- 终端输出形如 `当前版本号: 3.1.YYYYMMDDHH (请手动修改)`。

从输出中**抓取版本号**（即 `3.1.YYYYMMDDHH`），后续步骤记作 `<VER>`。

### 2. 更新 `server/settings.py` 的 `SYS_VERSION`

把 `SYS_VERSION = '<旧版本>'` 改为 `SYS_VERSION = '<VER>'`。

> 该字段是项目里唯一权威的版本号，前端 `/swagger` 也读它。

### 3. 检查 changelog 顶部内容

`Read` 一下 `changelog.md` 头 ~20 行，确认：
- 顶部是 `## <VER>`
- 自上次 tag 之后的提交都被分类列出。
- 如有内容明显不对（例如重复段、无关分类），先与用户确认，不要直接打 tag。

### 4. 提交 + 打 tag + 推送

参考过往风格（commit message 用 `release: <VER>`，tag 名直接用版本号、无 `v` 前缀）：

```bash
git add changelog.md server/settings.py
git commit -m "release: <VER>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>"
git tag <VER>
git push
git push origin <VER>
```

可以串成一个 `&&` 链一次执行。

### 5. 汇报

向用户简述：
- 本次版本号 `<VER>`。
- changelog 顶部新增了多少行 / 包含哪几类提交。
- commit hash、tag 名、master / tag 都已推到 origin。

## 注意事项

- **不要自己编版本号**：始终用 `update_changelog.sh` 输出里的那一个，不要试图改格式或日期。
- **`SYS_VERSION` 是必须改的**：脚本只更新 `changelog.md`，settings 必须手动同步，否则上线后接口返回的版本号还是旧的。
- **CRLF 警告可忽略**：Windows 上 `git commit` 会提示 `LF will be replaced by CRLF`，不是错误。
- **打 tag 前确认 working tree 干净**：除了本次 commit 的两个文件外，不应有其他未追踪/未提交的改动混进 release commit。如有，先单独 commit 或 stash。
- **失败回滚**：如果 push 失败需要回退，删除本地 tag (`git tag -d <VER>`) 与撤销 commit (`git reset --soft HEAD^`)；远端 tag 已 push 的删除需要先与用户确认。