versioning.md

版本管理

本文介绍项目的版本管理规范，包括版本号管理和 Windows 版本号映射。

版本号规范

项目版本命名遵循 Python 包版本规范。

更改版本

通过 uv version 命令更改应用版本。

# 查看当前版本
uv version

# 设置指定版本
uv version 1.2.3

# 提升补丁版本并标记为开发版
uv version --bump patch --bump dev

# 标记为稳定版本
uv version --bump stable

Tip

运行 uv version --help 可查看帮助。

Windows 版本号映射

Windows 可执行文件的 FixedFileInfo 中的文件版本和产品版本仅支持四个 16 位无符号整数（格式为 A.B.C.D）。

为保留应用版本的详细信息，采用以下映射规则：

• A.B.C 直接对应应用版本的 major.minor.micro。
• D（构建号）根据版本的预发布、开发、后发布状态计算得出。

计算公式

D = 基础偏移 + 预发布号 × 100 + 后发布号 × 10 +（开发号 或 9）

参数	说明
基础偏移	Alpha: 10000；Beta: 20000；RC: 30000；正式: 40000
预发布号	取 a、b、rc 后面的数字，无则为 0
后发布号	取 post 后面的数字，无则为 0
开发号	取 dev 后面的数字，此时不加 9；若非开发版本则加 9

映射示例

应用版本	FixedFileInfo 版本	计算过程
1.2.3.dev1	1.2.3.00001	0 + 0 + 0 + 1
1.2.3a	1.2.3.10009	10000 + 0 + 0 + 9
1.2.3a1.dev2	1.2.3.10102	10000 + 1×100 + 0 + 2
1.2.3a1	1.2.3.10109	10000 + 1×100 + 0 + 9
1.2.3a1.post2.dev3	1.2.3.10123	10000 + 1×100 + 2×10 + 3
1.2.3a1.post2	1.2.3.10129	10000 + 1×100 + 2×10 + 9
1.2.3b1	1.2.3.20109	20000 + 1×100 + 0 + 9
1.2.3rc1	1.2.3.30109	30000 + 1×100 + 0 + 9
1.2.3	1.2.3.40009	40000 + 0 + 0 + 9
1.2.3.post1.dev2	1.2.3.40012	40000 + 0 + 1×10 + 2
1.2.3.post1	1.2.3.40019	40000 + 0 + 1×10 + 9

语义化版本映射

由于 Python 包版本号与 语义化版本规范（SemVer） 存在差异，采用以下映射规则：

1. 基础版本：取 major.minor.micro。
2. 开发版（仅 dev，无预发布、无后发布）：附加 -alpha。
3. 预发布标识：a → -alpha，b → -beta，rc → -rc。
4. 预发布号：当预发布号非 0 时，附加 .{N}（如 a1 → -alpha.1，但 a 不附 .0）。
5. 预发布与开发版组合（如 a1.dev2）：按预发布规则生成，开发号不参与。
6. 后发布与开发版组合（如 post1.dev2）：与稳定版一致，不附加 -alpha。
7. 单独的后发布（如 post1）：不影响映射结果。

实现见 scripts/app_metadata.py 中的 get_semantic_version。

应用版本	语义化版本
1.2.3.dev1	1.2.3-alpha
1.2.3a	1.2.3-alpha
1.2.3a1.dev2	1.2.3-alpha.1
1.2.3a1	1.2.3-alpha.1
1.2.3a1.post2.dev3	1.2.3-alpha.1
1.2.3a1.post2	1.2.3-alpha.1
1.2.3b1	1.2.3-beta.1
1.2.3rc1	1.2.3-rc.1
1.2.3	1.2.3
1.2.3.post1.dev2	1.2.3
1.2.3.post1	1.2.3

相关文档

• 快速上手
• 构建指南
• 发布流程