ai-app-base-bump-version

bump-version-py

专为 Python 项目设计的智能语义化版本管理命令行工具。

简介

bump-version-py 是一个遵循 PEP 440 规范的 Python 项目版本管理工具。它可以自动更新项目版本号，创建 Git 提交和标签，简化版本发布流程。

主要功能

• ✅ 完全遵循 PEP 440 版本规范
• ✅ 支持 pyproject.toml 和 setup.py
• ✅ 支持预发布版本（alpha、beta、rc、dev、post）
• ✅ 自动 Git 集成（提交、标签、推送）
• ✅ 交互式命令行界面
• ✅ 内置版本号验证功能
• ✅ 安全检查（分支、工作区状态）

安装

# 使用 uv 全局安装
uv tool install ai-app-base-bump-version

开发安装

# 克隆仓库
git clone https://github.com/ai-app-base/bump-version-py.git
cd bump-version-py

# 安装依赖
uv sync

# 全局安装开发版本（类似 npm link）
uv tool install -e .

使用方法

版本升级

在项目根目录运行：

# 完整命令
bump-version-py

# 简写命令
bvp

工具会自动：

1. 检测当前版本
2. 提供交互式选项
3. 更新配置文件
4. 创建 Git 提交和标签
5. 推送到远程仓库（可选）

版本验证

使用 validate 子命令验证版本号是否符合 PEP 440 规范：

# 验证版本号
bump-version-py validate 1.0.0
bump-version-py validate 1.0.0a0
bvp validate 2.0.0.dev1

# 输出示例
✅ Version 1.0.0 is PEP 440 compliant  # 退出码 0
❌ Version 'invalid' is not PEP 440 compliant  # 退出码 1

在 CI/CD 中使用：

# 在 shell 脚本中
if bump-version-py validate "$VERSION"; then
  echo "版本号有效"
else
  echo "版本号无效"
  exit 1
fi

# 或使用 Python 模块
python -m bump_version.cli validate 1.0.0

版本格式

遵循 PEP 440 规范的版本号格式：

1.0.0          # 正式版本
1.0.0a0        # Alpha 版本
1.0.0b0        # Beta 版本
1.0.0rc0       # Release Candidate
1.0.0.dev0     # 开发版本
1.0.0.post0    # 后发布版本

配置文件支持

pyproject.toml（推荐）

[project]
name = "my-package"
version = "1.0.0"

# 或 Poetry 项目
[tool.poetry]
name = "my-package" 
version = "1.0.0"

setup.py

setup(
    name="my-package",
    version="1.0.0",
    ...
)

工作流程示例

基本发布流程

# 1. 开发完成，准备发布新版本
bvp
# 选择 "正式版本 (Production)"
# 选择 "Patch (修订号)"
# 版本：1.0.0 → 1.0.1

# 2. 自动完成
# - 更新 pyproject.toml
# - git commit -m "chore: release 1.0.1"
# - git tag v1.0.1
# - git push --follow-tags

预发布流程

# 1. 创建 Alpha 版本
bvp
# 选择 "Alpha 版本"
# 选择 "Minor (次版本号)"
# 版本：1.0.0 → 1.1.0a0

# 2. 升级到 Beta
bvp
# 选择 "Beta 版本"
# 版本：1.1.0a0 → 1.1.0b0

# 3. 发布正式版
bvp
# 选择 "正式版本 (Production)"
# 版本：1.1.0b0 → 1.1.0

环境变量

• BUMP_VERSION_SKIP_PUSH: 设置为任意值时跳过 git push

API 使用

在代码中使用版本验证功能：

from bump_version.cli import validate_version

if validate_version("1.0.0"):
    print("版本号有效")
else:
    print("版本号无效")

注意事项

1. 使用前确保：

   • 项目已初始化 Git 仓库
   • 工作区干净（无未提交的更改）
   • 在主分支（main/master）上操作

2. 版本号规范：

   • 必须符合 PEP 440 规范
   • 不要手动添加 'v' 前缀（工具会自动处理）

3. Git 标签格式：

   • 自动添加 'v' 前缀：v1.0.0

许可证

ISC