DiAL/openspec/specs/version-management/spec.md

Purpose

定义 DiAL 应用版本号的唯一来源、手动版本升迁命令和版本管理文档要求。

Requirements

Requirement: 应用版本唯一来源

系统 SHALL 使用根目录 package.json.version 作为 DiAL 应用版本号的唯一来源。版本号 MUST 使用 MAJOR.MINOR.PATCH 数字格式，不包含 prerelease 或 build metadata。

Scenario: 读取应用版本

• WHEN 开发、构建或版本升迁流程需要获取 DiAL 应用版本
• THEN 系统 SHALL 从根目录 package.json.version 读取版本号

Scenario: 版本格式有效

• WHEN package.json.version 为 0.1.0、1.2.3 等 MAJOR.MINOR.PATCH 数字格式
• THEN 版本管理流程 SHALL 视为有效版本

Scenario: 版本格式无效

• WHEN package.json.version 缺失或不符合 MAJOR.MINOR.PATCH 数字格式
• THEN 版本管理流程 MUST 失败并输出可读错误，不得继续写入错误版本

Requirement: 手动版本升迁命令

项目 SHALL 通过 package.json scripts 提供基于 Bun 的手动版本升迁命令，支持 patch、minor、major 和显式设置版本。

Scenario: 升迁 patch 版本

• WHEN 当前版本为 1.2.3 且开发者运行 bun run version:patch
• THEN 系统 SHALL 将 package.json.version 更新为 1.2.4

Scenario: 升迁 minor 版本

• WHEN 当前版本为 1.2.3 且开发者运行 bun run version:minor
• THEN 系统 SHALL 将 package.json.version 更新为 1.3.0

Scenario: 升迁 major 版本

• WHEN 当前版本为 1.2.3 且开发者运行 bun run version:major
• THEN 系统 SHALL 将 package.json.version 更新为 2.0.0

Scenario: 显式设置版本

• WHEN 开发者运行 bun run version:set 0.2.0
• THEN 系统 SHALL 将 package.json.version 更新为 0.2.0

Scenario: 拒绝无效设置版本

• WHEN 开发者运行 bun run version:set 1.0.0-beta.1 或其他非 MAJOR.MINOR.PATCH 版本
• THEN 系统 MUST 失败并保持 package.json.version 不变

Scenario: 版本升迁不执行发布副作用

• WHEN 开发者运行任意版本升迁命令
• THEN 系统 MUST NOT 自动创建 git commit、git tag、changelog 或 release

Requirement: 版本管理文档

项目 SHALL 在开发文档中说明版本号规则、升迁命令、展示位置和暂不支持的发布自动化能力。

Scenario: 开发者查阅版本规则

• WHEN 开发者阅读 README.md 或 DEVELOPMENT.md
• THEN 文档 SHALL 说明 package.json.version 是唯一版本源，以及 bun run version:patch、bun run version:minor、bun run version:major、bun run version:set <version> 的用途