Bump My Version

注意

这是对优秀的 bump2version 分支 的维护重构，重构的主要目标是

• 添加对 pyproject.toml 配置文件的支持。
• 将CLI界面转换为 click 和 rich
• 使用 Pydantic 添加更好的配置验证
• 使代码和测试更容易阅读和维护

概述

Bump My Version 的目的是

• 作为自动化构建系统的一部分
• 通过项目的开发生命周期管理项目版本
  • 递增版本号
  • 序列化版本号
  • 解析版本号
  • 支持SemVer、CalVer以及其他版本控制方案
• 修改项目文件作为项目开发生命周期的一部分
• 与项目的源代码控制系统协同工作
  • 提交更改
  • 标记发布版本
  • 从标签中读取版本号

安装

您可以通过以下方式从Python包索引（PyPI）下载并安装此软件的最新版本：

pip install --upgrade bump-my-version

变更日志

请在此处找到变更日志： CHANGELOG.md

语义版本控制示例

创建默认配置

默认配置使用简化版的语义版本控制。

$ bump-my-version sample-config --no-prompt --destination .bumpversion.toml
$ cat .bumpversion.toml
[tool.bumpversion]
current_version = "0.1.0"
parse = "(?P<major>\\d+)\\.(?P<minor>\\d+)\\.(?P<patch>\\d+)"
serialize = ["{major}.{minor}.{patch}"]
search = "{current_version}"
replace = "{new_version}"
regex = false
ignore_missing_version = false
tag = false
sign_tags = false
tag_name = "v{new_version}"
tag_message = "Bump version: {current_version} → {new_version}"
allow_dirty = false
commit = false
message = "Bump version: {current_version} → {new_version}"
commit_args = ""

可视化版本控制路径

您可以使用show-bump子命令查看潜在的版本控制路径。

$ bump-my-version show-bump
0.1.0 ── bump ─┬─ major ─ 1.0.0
               ├─ minor ─ 0.2.0
               ╰─ patch ─ 0.1.1
$ bump-my-version show-bump 1.2.3
1.2.3 ── bump ─┬─ major ─ 2.0.0
               ├─ minor ─ 1.3.0
               ╰─ patch ─ 1.2.4

默认配置仅允许升级主版本、次版本或补丁版本。如果您想支持预发布版本呢？

添加对预发布版本的支持

修改parse配置以支持预发布版本。此parse选项使用扩展的正则表达式从当前版本中提取版本组件。

parse = """(?x)
    (?P<major>0|[1-9]\\d*)\\.
    (?P<minor>0|[1-9]\\d*)\\.
    (?P<patch>0|[1-9]\\d*)
    (?:
        -                             # dash separator for pre-release section
        (?P<pre_l>[a-zA-Z-]+)         # pre-release label
        (?P<pre_n>0|[1-9]\\d*)        # pre-release version number
    )?                                # pre-release section is optional
"""

修改serialize配置以支持预发布版本。

serialize = [
    "{major}.{minor}.{patch}-{pre_l}{pre_n}",
    "{major}.{minor}.{patch}",
]

为pre_l部分添加新的配置部分。

[tool.bumpversion.parts.pre_l]
values = ["dev", "rc", "final"]
optional_value = "final"

可视化新的版本控制路径

现在，当您运行bump-my-version show-bump时，您可以看到新的预发布版本控制路径。

$ bump-my-version show-bump
0.1.0 ── bump ─┬─ major ─ 1.0.0-dev0
               ├─ minor ─ 0.2.0-dev0
               ├─ patch ─ 0.1.1-dev0
               ├─ pre_l ─ invalid: The part has already the maximum value among ['dev', 'rc', 'final'] and cannot be bumped.
               ╰─ pre_n ─ 0.1.0-final1

pre_l不可升级，因为它已经达到最大值。而pre_n可升级，因为它没有达到最大值。

如果我们运行bump-my-version show-bump 1.0.0-dev0，我们可以看到以dev开头的版本的新版本控制路径。

$ bump-my-version show-bump 1.0.0-dev0
1.0.0-dev0 ── bump ─┬─ major ─ 2.0.0-dev0
                    ├─ minor ─ 1.1.0-dev0
                    ├─ patch ─ 1.0.1-dev0
                    ├─ pre_l ─ 1.0.0-rc0
                    ╰─ pre_n ─ 1.0.0-dev1

最后，我们可以看到以rc开头的版本的新版本控制路径。

$ bump-my-version show-bump 1.0.0-rc0 
1.0.0-rc0 ── bump ─┬─ major ─ 2.0.0-dev0
                   ├─ minor ─ 1.1.0-dev0
                   ├─ patch ─ 1.0.1-dev0
                   ├─ pre_l ─ 1.0.0
                   ╰─ pre_n ─ 1.0.0-rc1

完整的发展与发布路径是

• 1.0.0
• bump patch → 1.0.1-dev0
• bump pre_n → 1.0.1-dev1
• bump pre_l → 1.0.1-rc0
• bump pre_n → 1.0.1-rc1
• bump pre_l → 1.0.1

1. 在开始开发之前，您必须决定下一个版本。
2. 使用bump-my-version bump pre_n升级开发版本。
3. 使用bump-my-version bump pre_l从开发版本切换到候选发布版本。
4. 使用bump-my-version bump pre_n升级候选发布版本。
5. 使用bump-my-version bump pre_l从候选发布版本切换到最终发布版本。

自动化预发布编号

pre_n或预发布编号是每次预发布都会增加的数字。您可以通过更改序列化配置来自动化。

serialize = [
    "{major}.{minor}.{patch}-{pre_l}{distance_to_latest_tag}",
    "{major}.{minor}.{patch}",
]

distance_to_latest_tag是一个特殊值，它被替换为自上次标签以来的提交次数。这对于pre_n是一个很好的值，因为它会随着每次提交而增加。

可视化pre_n版本控制路径

现在，当您运行bump-my-version show-bump时，您可以看到新的预发布版本控制路径。

$ bump-my-version show-bump
0.1.0 ── bump ─┬─ major ─ 1.0.0-dev0
               ├─ minor ─ 0.2.0-dev0
               ├─ patch ─ 0.1.1-dev0
               ╰─ pre_l ─ invalid: The part has already the maximum value among ['dev', 'rc', 'final'] and cannot be bumped.
$ bump-my-version show-bump 1.0.0-dev0
1.0.0-dev0 ── bump ─┬─ major ─ 2.0.0-dev0
                    ├─ minor ─ 1.1.0-dev0
                    ├─ patch ─ 1.0.1-dev0
                    ╰─ pre_l ─ 1.0.0-rc0
$ bump-my-version show-bump 1.0.0-rc0 
1.0.0-rc0 ── bump ─┬─ major ─ 2.0.0-dev0
                   ├─ minor ─ 1.1.0-dev0
                   ├─ patch ─ 1.0.1-dev0
                   ╰─ pre_l ─ 1.0.0

由于自动化，现在缺少了pre_n路径。

完整的发展与发布路径现在是

• 1.0.0
• bump patch → 1.0.1-dev0
  • 每个提交都会增加 → 1.0.1-dev1
• bump pre_l → 1.0.1-rc0
  • 每个提交都会增加 → 1.0.1-rc1
• bump pre_l → 1.0.1

1. 在开始开发之前，您必须决定下一个版本。
2. 开发版本会随着每个提交自动增加。
3. 使用bump-my-version bump pre_l从开发版本切换到候选发布版本。
4. 候选发布版本会随着每个提交自动增加。
5. 使用bump-my-version bump pre_l从候选发布版本切换到最终发布版本。

GitHub Actions

您可以将bump-my-version作为GHA工作流程的一部分使用。以下是一个示例工作流程，该工作流程升级版本，提交更改并标记提交。

name: Bump version

on:
  workflow_dispatch:
      bump-type:
        description: 'Bump type'
        required: true
        default: 'patch'
        type: choice
        options:
        - major
        - minor
        - patch

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout the code
        uses: actions/checkout@v4

      - name: Bump version
        id: bump
        uses: callowayproject/bump-my-version@master
        env:
          BUMPVERSION_TAG: "true"
        with:
          args: ${{ inputs.bump-type }}
          github-token: ${{ secrets.GH_TOKEN }}

      - name: Check
        if: steps.bump.outputs.bumped == 'true'
        run: |
          echo "Version was bumped from ${{ steps.bump.outputs.previous-version }} to ${{ steps.bump.outputs.current-version }}!"

bump-my-version动作的输入

1. args - 要传递给bump-my-version bump [args]命令的参数。有关更多信息，请参阅CLI文档。
2. github-token - 用于提交和标记的GitHub令牌。这是可选的。

输出

1. bumped - 表示是否已升级版本的布尔标志。
2. previous-version - 执行升级操作前的版本。
3. current-version - 执行版本增量后的版本。

如果您想确保使用“on-push”触发器设置的流程也能根据新推送的提交或标签启动，您需要提供自定义PAT（github-token）。请参阅这里。

开发 & 贡献

感谢贡献者们！您可以在这里找到完整的列表：https://github.com/callowayproject/bump-my-version/graphs/contributors

也请参阅我们的CONTRIBUTING.md

此项目的开发在GitHub上进行，包括测试和文档的补丁非常欢迎，以及错误报告！如果您发现此工具不支持您开发工作流程中增量版本的所有方面，请创建一个问题，因为它旨在非常灵活。

许可协议

Bump My Version遵循MIT许可证 - 有关详细信息，请参阅LICENSE文件。