WhaleFall 版本更新

输入

• 目标版本号 X.Y.Z(语义化版本).
• 本次发版主题/一句话摘要(用于 CHANGELOG.md 与 About 时间轴).

工作流

1. 读取强一致清单并确认当前版本号.
   • 需要完整指南时,读取 references/VERSION_UPDATE_GUIDE.md.
2. 优先更新 app/settings.py 的 APP_VERSION,再同步其余文件.
3. 更新 CHANGELOG.md 与 app/templates/about.html 的本次发版记录.
4. 运行自检脚本与质量命令,核对 git status 只包含必要文件.

强一致文件清单(必须同步)

• app/settings.py: 更新 APP_VERSION(运行时版本号唯一来源).
• pyproject.toml: 更新 [project].version.
• env.example: 更新 APP_VERSION=....
• uv.lock: 在 [[package]] name = "whalefalling" 节点更新 version = "...".
• scripts/deploy/deploy-prod-all.sh: 更新脚本头部注释/横幅/日志中的版本号.
• app/routes/main.py: 更新 app_version 返回值(供前端展示).
• app/templates/base.html: 更新页脚版本展示.
• nginx/error_pages/404.html 与 nginx/error_pages/50x.html: 更新错误页版本展示.
• README.md: 更新顶部徽章与底部“最后更新/版本”.
• CHANGELOG.md: 顶部新增或更新本次版本条目(倒序).
• app/templates/about.html: 时间轴追加本次版本记录(不改历史条目).

验证与自检

1. 运行版本一致性自检脚本(本 skill 自带): python3 scripts/check_version_sync.py --root <repo_root> --expected X.Y.Z.
   • 不传 --expected 时,脚本会从 app/settings.py 的 APP_VERSION 推导并作为期望值.
2. 运行质量/检查命令(按需选择): make quality 或 ruff check <files>.
3. 核对 git status/git diff,避免仅为版本号而改动 docs/architecture/*、docs/reports/* 等大文档.

输出模板

• 提交信息: chore: bump version to X.Y.Z 或 chore: release vX.Y.Z.
• PR 核对清单:
  • app/settings.py 的 APP_VERSION 已更新并作为基准值
  • pyproject.toml/env.example/uv.lock 已同步
  • /admin/api/app-info 的 app_version 已同步
  • 页脚/错误页/README 已同步
  • CHANGELOG.md 与 About 时间轴已补充
  • python3 scripts/check_version_sync.py --root <repo_root> 通过

兼容与回退

• 若仓库中缺少指南里提到的历史脚本(例如 check_missing_docs_smart.py),使用 make quality 作为回退验证.
• 若依赖文件出现与项目版本相同的数字,先确认是否为第三方依赖版本,避免误替换.