1
0

feat: 迁移 versionctl 为独立模块并新增 make version-bump 命令

- 将 backend/cmd/versionctl 和 backend/pkg/projectversion 迁移至独立 versionctl/ Go 模块
- 新增 bump 子命令支持 major/minor/patch 和指定版本号,含版本倒退防护
- 新增 make version-bump 编排完整升迁流程(bump + sync + check + commit + tag)
- 更新所有引用路径:根 Makefile、backend/Makefile、release.yml、.golangci.yml
- 新增 versionctl/.golangci.yml(精简配置)和 Makefile(lint/test/coverage)
- 根 Makefile lint/test 集成 versionctl 模块
- 同步 openspec specs:新增 version-bump spec,更新 release-pipeline spec
This commit is contained in:
2026-05-05 04:18:10 +08:00
parent 3cd0458c2c
commit bc7a7c6e81
16 changed files with 515 additions and 47 deletions

View File

@@ -8,18 +8,28 @@
### Requirement: Tag 驱动发布流水线
系统 SHALL 仅在符合 `vX.Y.Z` 格式的 Git tag 上触发发布流水线,普通分支 push SHALL NOT 创建发布。
系统 SHALL 仅在符合 `vX.Y.Z` 格式的 Git tag 上触发发布流水线,普通分支 push SHALL NOT 创建发布。发布流水线 SHALL 使用 `./versionctl` 而非 `./backend/cmd/versionctl` 调用版本管理工具。
#### Scenario: 有效发布 tag
- **WHEN** 仓库收到 `v1.2.3` tag push
- **THEN** 发布流水线 SHALL 启动版本校验、构建和 Release 组装步骤
- **AND** 版本校验步骤 SHALL 使用 `go run ./versionctl print``go run ./versionctl verify-tag` 获取并验证版本
#### Scenario: 普通分支推送
- **WHEN** 仓库收到非 tag 的分支 push
- **THEN** 系统 SHALL NOT 创建 GitHub Release
### Requirement: 发布流水线 Go 模块缓存覆盖
发布流水线 SHALL 在所有 Go module 的 go.sum 文件存在时正确设置 Go 模块缓存路径,确保新增的 `versionctl` module 依赖也被缓存。
#### Scenario: CI 缓存覆盖所有 module
- **WHEN** 发布流水线设置 Go 模块缓存
- **THEN** `cache-dependency-path` SHALL 覆盖 `backend/go.sum``versionctl/go.sum`
### Requirement: 三平台发布构建
系统 SHALL 在发布流水线中构建 server 与 desktop 的 Linux、Windows、macOS 三个平台产物。

View File

@@ -0,0 +1,113 @@
# 版本升迁
## Purpose
定义 `version bump` 子命令的版本号递增、下游文件同步、倒退防护及 Makefile 编排规则,确保版本升迁流程安全可自动化。
## Requirements
### Requirement: 版本号递增
`version bump` 子命令 SHALL 支持三种递增模式:`major`major+1, minor=0, patch=0`minor`minor+1, patch=0`patch`patch+1以及直接指定具体版本号。
#### Scenario: minor 递增
- **WHEN** 当前 VERSION 为 `0.1.0`,执行 `version bump minor`
- **THEN** VERSION 文件 SHALL 被更新为 `0.2.0`
#### Scenario: major 递增
- **WHEN** 当前 VERSION 为 `0.1.0`,执行 `version bump major`
- **THEN** VERSION 文件 SHALL 被更新为 `1.0.0`
#### Scenario: patch 递增
- **WHEN** 当前 VERSION 为 `0.1.0`,执行 `version bump patch`
- **THEN** VERSION 文件 SHALL 被更新为 `0.1.1`
#### Scenario: 指定具体版本号
- **WHEN** 当前 VERSION 为 `0.1.0`,执行 `version bump 1.0.0`
- **THEN** VERSION 文件 SHALL 被更新为 `1.0.0`
#### Scenario: 指定版本号等于当前 VERSION
- **WHEN** 当前 VERSION 为 `0.1.0`,执行 `version bump 0.1.0`
- **THEN** 命令 SHALL 正常执行,完成 sync 和 check输出 `0.1.0`
#### Scenario: 非法 bump 参数
- **WHEN** 执行 `version bump` 传入既非 `major|minor|patch` 也非合法 semver 的参数
- **THEN** 命令 SHALL 以非零退出码失败并输出错误信息
### Requirement: bump 自动同步下游文件
`version bump` 子命令 SHALL 在写回 VERSION 文件后自动执行 sync 和 check确保 `frontend/package.json` 和所有 `frontend/.env.*` 文件与新版本号一致。
#### Scenario: bump 自动 sync 和 check
- **WHEN** 执行 `version bump minor` 且当前 VERSION 为 `0.1.0`
- **THEN** 命令 SHALL 自动将新版本号 `0.2.0` 同步到 `frontend/package.json``version` 字段和所有 `frontend/.env.*``VITE_APP_VERSION` 变量
- **AND** 命令 SHALL 自动验证所有下游文件版本号一致性
#### Scenario: sync 失败时 bump 中止
- **WHEN** 执行 `version bump minor` 但下游文件同步失败(如文件缺失)
- **THEN** 命令 SHALL 以非零退出码失败
### Requirement: 版本号倒退防护
`version bump` 子命令 SHALL 检查新版本号严格大于所有已有 git tag 中的最大版本号,防止版本号倒退。
#### Scenario: 新版本大于已有 tag
- **WHEN** 已有 tag `v0.1.0`,执行 `version bump minor`
- **THEN** 命令 SHALL 成功将版本更新为 `0.2.0`
#### Scenario: 新版本等于已有 tag
- **WHEN** 已有 tag `v0.1.0`,执行 `version bump 0.1.0`
- **THEN** 命令 SHALL 以非零退出码失败并提示版本号已存在
#### Scenario: 新版本小于已有 tag
- **WHEN** 已有 tag `v0.2.0`,执行 `version bump 0.1.5`
- **THEN** 命令 SHALL 以非零退出码失败并提示版本号倒退
#### Scenario: 无已有 tag
- **WHEN** 不存在任何 `v*.*.*` 格式的 git tag执行 `version bump 0.1.0`
- **THEN** 命令 SHALL 成功
### Requirement: bump 输出新版本号
`version bump` 子命令成功时 SHALL 仅将新版本号(不含 `v` 前缀)输出到 stdout供 Makefile 等外部工具使用。
#### Scenario: 输出格式
- **WHEN** 执行 `version bump minor`,当前版本为 `0.1.0`
- **THEN** stdout SHALL 输出 `0.2.0`(换行结尾,无额外内容)
### Requirement: 版本升迁 Makefile 编排
`make version-bump` SHALL 编排完整的版本升迁流程:工作区干净检查 → `version bump`(含 sync/check/倒退检查)→ git add → git commit → git tag。
#### Scenario: 完整升迁流程
- **WHEN** 执行 `make version-bump BUMP=minor`,工作区干净,当前版本 `0.1.0`
- **THEN** Makefile SHALL 依次执行:工作区检查 → `version bump minor``git add VERSION frontend/``git commit -m "chore: 版本升迁 v0.2.0"``git tag v0.2.0`
#### Scenario: 工作区不干净
- **WHEN** 执行 `make version-bump BUMP=minor`,但工作区有未提交的改动
- **THEN** Makefile SHALL 以非零退出码失败并提示先提交或暂存改动
#### Scenario: 支持指定版本号
- **WHEN** 执行 `make version-bump SET_VERSION=1.0.0`
- **THEN** Makefile SHALL 将 `1.0.0` 传递给 `version bump` 子命令
#### Scenario: 不自动推送
- **WHEN** `make version-bump` 成功完成
- **THEN** commit 和 tag SHALL 仅存在于本地SHALL NOT 自动 push 到远程