lanyuanxiaoyao/nex
1
0
Fork 0
Code Activity
Files
32f48777f3bffb5aa458cb306fe97556634f2848
nex/openspec/specs/version-bump/spec.md

4.8 KiB
Raw Blame History

版本升迁

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 到远程
View Git Blame Copy Permalink