docs: 发版流程拆成通用与项目两层

现象:AGENTS.md「发版本流程」里写死了本项目的文件名和命令(metadata.yaml、uv tool run
bump-my-version、uv.lock),换项目没法直接复用;手写那一行还出现了 `runm` 和 `etadata.yaml`
两处笔误。

根因:通用规则和项目实现细节混在同一节,规则文件承担了本该属于架构文档的内容。

边界:
- AGENTS.md「发版本流程」改成通用表述:确认后触发、CHANGELOG 整理、锁文件自检、发版工具一次
  完成改版本 + 提交 + 打 tag、tag 查重、发版不构建;不再出现具体文件名和命令
- docs/architecture.md 新增「发版」一节,放本项目的三处版本文件、bump-my-version 命令、
  CRLF + regex 的配置坑、改配置后先 dry-run
- docs/agent_workflow.md「项目契约和 Agent 行为规则分开」补上这次的证据,Seen 升到 2×
- 不改代码、不改版本号、不打 tag

运行了什么:git status 自查(只提交这 3 个文档文件);提交时 pre-commit 跑 ruff / web typecheck / commitizen
没跑什么:没跑 bump-my-version 真实发版;没跑测试、没构建(本次无代码改动)
This commit is contained in:
study-tool
2026-11-01 21:22:56 +08:00
parent d8808e64d9
commit 48e72ab1e7
3 changed files with 20 additions and 5 deletions
+6 -4
View File
@@ -76,12 +76,14 @@
## 发版本流程
本节是通用流程;本项目的版本文件、发版命令和配置细节见 `docs/architecture.md`「发版」。
- 发版本只在用户明确确认后触发;触发前工作区必须干净(见「收尾」)。
- 先把 `CHANGELOG.md` 的 `Unreleased` 变更整理成新的版本记录,保留空的 `Unreleased` 标题,并作为一个普通提交先提交。
- 发版前跑一次 `uv lock` 自检:它若改动了 `uv.lock`,说明某个任务漏提交了锁文件——补进那次任务,不为它单开提交。
- 工作区干净后执行 `uv tool run bump-my-version bump patch`:它一次完成「改 `metadata.yaml` / `pyproject.toml` / `uv.lock` 三处 `version` + 自动提交 + 自动打 tag」,**不要再手动 commit 或 `git tag`**。普通提交不动版本号。
- 发完用 `git log -1` 和 `git tag -l` 确认 tag 存在、HEAD 正确;打 tag 前工具会失败于同名 tag,不覆盖已有 tag。
- 发版本流程中不要执行编译、测试或构建,除非用户明确要求;前端改动仍需 `pnpm build` 并把 `static/` 一起提交(在发版前的普通提交里完成)。
- 发版前先做依赖锁文件自检:锁文件若有变化,说明某个任务漏提交了它——补进那次任务,不为它单开提交。
- 版本号只在发版时提升,普通提交不动版本号;用项目配置好的发版工具一次完成「改版本号 + 提交 + 打 tag」,**不要再手动 commit 或打 tag**。
- 打 tag 前确认没有同名 tag,不覆盖已有 tag;发完确认 tag 存在、HEAD 正确。
- 发版本流程中不要执行编译、测试或构建,除非用户明确要求;产物(如前端构建)在发版前的普通提交里完成。
## 项目契约