161 lines
5.1 KiB
Markdown
161 lines
5.1 KiB
Markdown
---
|
||
description: 发版工作流：根据变更类型决定版本号，更新所有版本文件和 changelog，运行验证，commit 并 push
|
||
argument-hint: 可选：feature | bugfix | 或直接描述本次发布内容
|
||
allowed-tools: ["Read", "Edit", "Bash", "Glob", "Grep"]
|
||
---
|
||
|
||
# /release — Planet 发版工作流
|
||
|
||
## 版本号规则
|
||
|
||
| 变更类型 | 版本跳动 | 适用场景 |
|
||
|---------|---------|---------|
|
||
| `feature` | `+0.1.0` | 纯新功能，无 bugfix |
|
||
| `improvement` | `+0.0.1` | UI 调整、小功能增强、bugfix 混合，或以 UI/体验改进为主的迭代 |
|
||
| `bugfix` | `+0.0.1` | 纯 bug 修复，无新功能 |
|
||
| `docs` / `maintenance` / `refactor` | 默认不发版，除非用户明确要求 |
|
||
|
||
意图混合时以用户明确描述为准；bugfix + 小 feature 混合默认判定为 `improvement`（`+0.0.1`）。
|
||
|
||
## 必须同步更新的文件
|
||
|
||
使用 `git rev-parse --show-toplevel` 获取仓库根目录，以下路径均相对于根目录：
|
||
|
||
- `VERSION`
|
||
- `frontend/package.json`（`"version"` 字段）
|
||
- `pyproject.toml`（`version =` 字段）
|
||
- `uv.lock`（**不要手动编辑**，通过 `uv lock` 重新生成）
|
||
- `docs/CHANGELOG.md`
|
||
- `docs/version-history.md`
|
||
|
||
## 节省上下文规则
|
||
|
||
发版判断应以确定性 CLI 证据为主，优先使用紧凑命令和定点读取：
|
||
|
||
```bash
|
||
git status --short
|
||
git diff --stat HEAD
|
||
git diff --name-only HEAD
|
||
rg -n "version|^## |^Released:|当前开发版本|current" VERSION frontend/package.json pyproject.toml docs/CHANGELOG.md docs/version-history.md
|
||
```
|
||
|
||
除非需要判断某个代码变更是否属于本次发版，否则不要读取完整 diff。
|
||
|
||
## 执行步骤
|
||
|
||
### Step 1 — 环境检查
|
||
|
||
```bash
|
||
git branch --show-current # 确认在 dev 分支
|
||
git status --short # 检查是否有无关的未暂存修改
|
||
cat VERSION # 读取当前版本
|
||
```
|
||
|
||
若当前**不在 `dev` 分支**，停下来告知用户，不要继续。
|
||
|
||
若存在无关的未暂存修改，列出并询问用户是否一并提交，或先 stash。
|
||
|
||
### Step 2 — 确定发版类型与新版本号
|
||
|
||
- 若 `$ARGUMENTS` 提供了明确类型（`feature` / `bugfix`），直接使用
|
||
- 否则根据 `git diff --stat HEAD`、`git diff --name-only HEAD`、必要的 focused diff 和 `git log` 推断
|
||
- 计算新版本号（例：`0.26.2` → bugfix → `0.26.3`）
|
||
- **先输出发版计划供用户确认**：
|
||
|
||
```
|
||
发版计划：
|
||
类型：bugfix
|
||
版本：0.26.2 → 0.26.3
|
||
分支：dev
|
||
将更新：VERSION, frontend/package.json, pyproject.toml, uv.lock, CHANGELOG.md, version-history.md
|
||
```
|
||
|
||
### Step 3 — 更新版本号文件
|
||
|
||
按顺序更新（每步用 Edit 工具，精确替换，不要重写整个文件）：
|
||
|
||
1. `VERSION` — 直接替换全部内容为新版本号
|
||
2. `frontend/package.json` — 替换 `"version": "x.x.x"` 行
|
||
3. `pyproject.toml` — 替换 `version = "x.x.x"` 行
|
||
4. 运行 `uv lock` 重新生成 `uv.lock`（在仓库根目录下执行）
|
||
|
||
### Step 4 — 更新 CHANGELOG.md
|
||
|
||
在文件顶部插入新条目，格式：
|
||
|
||
```markdown
|
||
## [x.x.x] — YYYY-MM-DD
|
||
|
||
### ✨ Features / 🐛 Fixes / 🔧 Improvements
|
||
- ...（只列高信号条目，最多 5 条）
|
||
- ...
|
||
|
||
---
|
||
```
|
||
|
||
日期使用 `date +%Y-%m-%d` 获取今天的日期。
|
||
|
||
### Step 5 — 更新 docs/version-history.md
|
||
|
||
- 更新文件头部的"当前开发版本"字段
|
||
- 在时间线表格顶部插入新行：`| vx.x.x | YYYY-MM-DD | 一句话摘要 |`
|
||
|
||
### Step 6 — 验证
|
||
|
||
针对本次变更范围做最小验证：
|
||
|
||
- Python 文件有修改：先用 `git diff --name-only HEAD -- '*.py'` 列出，再运行 `python3 -m py_compile <changed_files>`
|
||
- Frontend 文件有修改：先用 `git diff --name-only HEAD -- frontend` 判断范围，再运行项目标准检查（若无则跳过并说明）
|
||
- 版本号一致性检查：用 grep 确认 VERSION、package.json、pyproject.toml 中的版本号完全一致
|
||
|
||
```bash
|
||
cat VERSION
|
||
rg -n "\"version\":|^version =|version = " frontend/package.json pyproject.toml uv.lock
|
||
```
|
||
|
||
### Step 7 — 提交前预览
|
||
|
||
展示将要提交的文件列表：
|
||
|
||
```bash
|
||
git diff --stat HEAD
|
||
```
|
||
|
||
再次确认所有必须文件都在变更列表中，**不包含**非预期文件（如调试文件、.env 等）。
|
||
|
||
### Step 8 — Commit & Push（用户确认后）
|
||
|
||
```bash
|
||
git add VERSION frontend/package.json pyproject.toml uv.lock docs/CHANGELOG.md docs/version-history.md
|
||
# 若有代码变更也一并 stage
|
||
git add <code_files>
|
||
|
||
git commit -m "release: bump version to x.x.x"
|
||
git tag vx.x.x
|
||
git push origin dev
|
||
git push origin vx.x.x
|
||
```
|
||
|
||
commit message 固定格式：`release: bump version to x.x.x`
|
||
|
||
### Step 9 — 完成确认
|
||
|
||
输出摘要：
|
||
|
||
```
|
||
✓ 版本号已更新：0.26.2 → 0.26.3
|
||
✓ CHANGELOG 已更新
|
||
✓ version-history 已更新
|
||
✓ uv.lock 已重新生成
|
||
✓ 验证通过
|
||
✓ commit: release: bump version to 0.26.3
|
||
✓ tag: v0.26.3
|
||
✓ 已 push 到 origin/dev
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
- `uv.lock` 只能通过 `uv lock` 生成，绝不手动编辑
|
||
- 发版 commit 只包含版本文件 + 本次功能代码，不混入无关改动
|
||
- 若环境中 `uv` 不可用，说明原因并跳过 lockfile 更新，提醒用户手动运行
|