Bumpversion实现可选开发版本后缀的配置指南

理解 Bumpversion 的版本部分机制

Bumpversion 是一个强大的版本管理工具，它通过解析（parse）和序列化（serialize）版本字符串，并根据预定义的“部分”（part）来递增版本。每个版本部分，如 major、minor、patch 或自定义的 dev、build 等，都可以定义其允许的值列表（values）。当 bumpversion 尝试递增某个部分时，它会查找该部分在 values 列表中的当前位置，并尝试移动到下一个值。

原始配置的问题分析

在原始配置中，为了实现可选的 dev 版本后缀，bumpversion 的 parse 规则包含了可选的 dev 和 build 部分：

[bumpversion]
current_version = 1.5.3
parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(-(?P<dev>.*)-(?P<build>\d+))?
serialize =
    {major}.{minor}.{patch}-{dev}-{build}
    {major}.{minor}.{patch}

[bumpversion:part:dev]
values =
    dev

[bumpversion:part:build]
first_value = 1

问题出在 [bumpversion:part:dev] 部分的 values 定义。它只包含了一个值 dev。当 current_version 是 1.5.3（即没有 dev 后缀）时，bumpversion 尝试通过 bumpversion dev 命令将版本递增到 dev 状态。然而，由于 dev 部分的 values 列表中只有一个 dev 值，bumpversion 认为 dev 部分已经处于其唯一可能的“最大值”状态，无法再向上递增，因此抛出 ValueError: The part has already the maximum value among ['dev'] and cannot be bumped. 错误。bumpversion 需要一个“起始状态”才能进行“递增”操作。

解决方案：引入初始空状态

解决此问题的关键在于为 dev 版本部分提供一个初始的、非 dev 的状态，以便 bumpversion 有一个可以“递增”的起点。最简单有效的方法是在 values 列表中添加一个空字符串 "" 作为第一个值。

修改后的 [bumpversion:part:dev] 配置如下：

[bumpversion:part:dev]
values =
    ""
    dev

完整的 bumpversion 配置示例：

Trae国内版

国内首款AI原生IDE，专为中国开发者打造

815

查看详情

[bumpversion]
current_version = 1.5.3
parse = (?P<major>\d+)\.(?P<minor>\d+)\.(?P<patch>\d+)(-(?P<dev>.*)-(?P<build>\d+))?
serialize =
    {major}.{minor}.{patch}-{dev}-{build}
    {major}.{minor}.{patch}

[bumpversion:part:dev]
values =
    ""
    dev

[bumpversion:part:build]
first_value = 1

通过这种修改，当 current_version 为 1.5.3 时，bumpversion 会将 dev 部分识别为处于 "" 状态。此时执行 bumpversion dev 命令，bumpversion 就能顺利地将 dev 部分从 "" 状态递增到 dev 状态。

操作示例与效果

假设初始版本为 1.5.3：

1. 执行 bumpversion dev：current_version 将从 1.5.3 变为 1.5.3-dev-1。此时，dev 部分从 "" 变为了 dev，build 部分从 first_value（即 1）开始计数。

2. 再次执行 bumpversion dev：bumpversion 会发现 dev 部分已经处于 dev 状态，并且在 values 列表中 dev 是最后一个值，因此会再次抛出错误。这是因为 bumpversion 的递增是非循环的，一旦达到 dev 状态，就不会再通过 bumpversion dev 命令返回到 "" 状态。

3. 执行 bumpversion patch： 如果当前版本是 1.5.3-dev-1，执行 bumpversion patch 会将版本递增到 1.5.4。此时，dev 和 build 部分会被移除，因为 serialize 规则中 patch 递增后会使用不带 dev-build 后缀的格式 {major}.{minor}.{patch}。

注意事项

• 非循环递增： 一旦 dev 部分从 "" 状态递增到 dev 状态，它不会通过再次执行 bumpversion dev 命令循环回到 "" 状态。如果需要移除 dev 后缀，通常是通过递增其他版本部分（如 patch、minor、major），让 serialize 规则选择不带 dev 后缀的格式。
• 初始值的灵活性： 除了 ""，你也可以使用任何其他不冲突的字符串作为 dev 部分的初始值，例如 13423423。只要它不是 dev 并且是 values 列表中的第一个元素，就能起到“占位符”的作用，提供一个可供递增的起始点。
• parse 和 serialize 规则的重要性： 确保 parse 正则表达式能够正确匹配带 dev 后缀和不带 dev 后缀的版本，并且 serialize 规则能根据当前版本状态选择正确的输出格式。这是实现可选后缀的基础。

总结

在 bumpversion 中配置可选的版本部分（如 dev 后缀）时，为了避免“无法递增”的错误，务必在对应部分的 values 列表中添加一个初始的、非目标状态的占位符（例如空字符串 ""）。这为 bumpversion 提供了一个明确的起始点，使其能够从“无此部分”的状态顺利过渡到“有此部分”的状态，从而实现更灵活、更健壮的版本管理流程。

以上就是Bumpversion实现可选开发版本后缀的配置指南的详细内容，更多请关注php中文网其它相关文章！