MaaFramework项目版本号规范设计与实践

版本号是软件开发中至关重要的标识符，它不仅用于区分不同版本的软件，还承载着版本演进、兼容性等重要信息。MaaFramework项目近期针对版本号定义进行了RFC讨论，旨在建立一套科学、规范的版本号体系，以适应不同软件包管理器的需求。

版本号结构设计

MaaFramework采用了语义化版本号(SemVer)的基本理念，并在此基础上进行了扩展，形成了以下结构：

<Version Core>[-<Version Unique ID>][+<Version Metadata>]

版本核心(Version Core)

版本核心遵循主版本号.次版本号.修订号的基本结构，并增加了预发布和发布后标识：

主版本号.次版本号.修订号[-(alpha|beta|rc).预发布号][-post.发布后号]

• 主版本号：重大更新，可能包含不兼容的API变更
• 次版本号：向后兼容的功能新增
• 修订号：向后兼容的问题修正
• 预发布号：标识alpha/beta/rc等预发布版本
• 发布后号：记录Tag发布后的commit次数

版本唯一标识(Version Unique ID)

为确保每次构建的唯一性，系统设计了两种标识方式：

(ci.持续集成号|dev.本地构建号)

• 持续集成号：使用GitHub Actions的run_id作为唯一标识
• 本地构建号：推荐使用Unix时间戳保证唯一性

版本元数据(Version Metadata)

元数据部分采用灵活的结构设计：

[${other_metadata}].[${commit_hash}.${date%Y%m%d}]

元数据使用点号分隔，仅允许使用字母数字字符，保证了兼容性。

实际应用示例

在CI环境中，版本号可能呈现为：

1.2.3-post.5-ci.12345678+abc123.20240505

本地开发构建可能为：

1.2.3-post.5-dev.1712345678+abc123.20240505

正式发布版本则更为简洁：

1.2.3

技术实现考量

1. 正则表达式验证：设计了严格的正则表达式来验证版本号格式，支持多种编程语言环境
2. 自动化生成：版本号各组成部分均可通过构建系统自动获取和组合
3. 兼容性保障：遵循SemVer基本原则，同时扩展部分不影响核心版本号的解析
4. 唯一性保证：通过CI编号或时间戳确保每次构建都有唯一标识

最佳实践建议

1. Tag命名应严格遵循v主版本号.次版本号.修订号[-(alpha|beta|rc).预发布号]格式
2. 预发布阶段使用alpha/beta/rc标识，便于区分稳定性
3. 发布后号(post)应自动计算，反映实际代码变更
4. 元数据部分应保持简洁，避免包含不必要的信息

这套版本号规范不仅解决了软件包管理器的兼容性问题，还为项目的版本管理提供了清晰的指导，有助于开发者、用户和自动化工具准确理解每个版本的含义和定位。