Setuptools项目版本管理完全指南

Setuptools项目版本管理完全指南

版本号的重要性

在Python项目开发中，版本号是项目生命周期管理的关键要素。它不仅帮助开发者追踪项目进展，还直接影响依赖解析和包管理。Setuptools作为Python生态中最主流的打包工具，对版本号有着完善的支持机制。

PEP 440标准与版本号组成

Python社区通过PEP 440规范了版本号的格式标准，Setuptools主要遵循这一规范，同时也兼容传统版本格式。一个标准的版本号由以下几部分组成：

1. 主版本号：如2、3等重大变更
2. 次版本号：如.4、.5等新增功能
3. 修订号：如.1、.2等错误修复
4. 预发布标签：如a(alpha)、b(beta)、rc(候选版本)
5. 发布后标签：如.post1等后续构建

版本号比较规则

• 2.4 > 2.4rc1 > 2.4b1 > 2.4a1
• 2.4.post1 > 2.4 但 < 2.4.1
• 2.10 > 2.9 > 2.1 (注意不是简单的字符串比较)

预发布标签详解

预发布标签表示尚未稳定的版本，常见的有：

• alpha/a：内部测试版
• beta/b：公开测试版
• rc：发布候选版
• dev：开发版

Setuptools还特别支持以下等价标签：

• c = rc
• pre = rc
• preview = rc

发布后标签使用

发布后标签常用于标记构建信息：

• .post1：第一个发布后版本
• .post20051127：日期戳版本
• 传统格式：-r1263或-20051127

开发版本管理实践

日常构建版本

在持续集成/持续交付(CI/CD)流程中，可以使用以下方式标记开发版本：

python setup.py egg_info -rbDEV bdist_egg

这会生成类似1.0.dev123的版本号，其中123可以是SVN版本号。

版本号验证技巧

使用pkg_resources.parse_version()验证版本号逻辑：

from pkg_resources import parse_version
assert parse_version("1.9.a.dev") == parse_version("1.9a0dev")
assert parse_version("2.1-rc2") < parse_version("2.1")

正式发布流程

当准备正式发布时，应清除所有开发标签：

python setup.py egg_info -Db "" sdist bdist_egg

建议为这个常用操作创建别名：

python setup.py alias -u release egg_info -Db ""

之后只需运行：

python setup.py release sdist bdist_egg

版本管理最佳实践

1. 明确版本策略：在项目早期确定版本号规则
2. 预发布清晰标记：让用户明确知道版本稳定性
3. 自动化版本生成：考虑使用setuptools-scm自动生成版本
4. 保持一致性：开发、测试和生产环境使用相同版本规则
5. 文档记录：在README中说明版本号含义

通过合理使用Setuptools的版本管理功能，可以确保项目在整个开发生命周期中保持清晰、一致的版本追踪，为依赖管理和发布流程打下坚实基础。