124 lines
4.8 KiB
Markdown
124 lines
4.8 KiB
Markdown
# 版本升迁
|
||
|
||
## 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。不传 `BUMP` 参数时 SHALL 默认执行 `BUMP=patch`。
|
||
|
||
#### 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: 不传 BUMP 默认 patch
|
||
|
||
- **WHEN** 执行 `make version-bump`，工作区干净，当前版本 `0.1.0`
|
||
- **THEN** Makefile SHALL 等效于执行 `make version-bump BUMP=patch`，将版本更新为 `0.1.1`
|
||
|
||
#### 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: SET_VERSION 优先于默认 BUMP
|
||
|
||
- **WHEN** 执行 `make version-bump SET_VERSION=2.0.0`
|
||
- **THEN** Makefile SHALL 使用 `SET_VERSION=2.0.0` 而非默认的 `BUMP=patch`
|
||
|
||
#### Scenario: 不自动推送
|
||
|
||
- **WHEN** `make version-bump` 成功完成
|
||
- **THEN** commit 和 tag SHALL 仅存在于本地，SHALL NOT 自动 push 到远程
|