bumpversion 可选开发后缀策略与实践

引言

在软件开发生命周期中，版本管理是至关重要的一环。bumpversion 是一个流行的命令行工具，用于自动化项目版本号的递增和管理，它能够通过配置文件定义复杂的版本格式和递增规则。在实际开发过程中，我们经常需要为预发布版本或开发构建添加特定的后缀，例如 1.0.0-dev-1，以区分正式发布版本。本文将探讨如何配置 bumpversion 以支持这种可选的开发版本后缀，并解决可能遇到的常见问题。

挑战：单值版本部分的限制

当尝试使用 bumpversion 管理一个可选的版本部分（例如 dev 后缀）时，如果该部分在配置文件中只定义了一个 value，就会遇到问题。考虑以下 bumpversion 配置片段：

[bumpversion:part:dev]
values =
    dev

当 current_version 为 1.5.3，且尝试执行 bumpversion dev 命令时，bumpversion 会报错：ValueError: The part has already the maximum value among ['dev'] and cannot be bumped.。这是因为 bumpversion 解释 values 列表时，如果只有一个值，它会认为该值已经是该部分的“最大”状态，因此无法再进行“递增”操作。它需要一个“起始”状态才能进行状态转换。

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

解决此问题的核心在于为可选的版本部分提供一个“起始”状态。通过在 dev 版本部分的 values 列表中添加一个空字符串 "" 或任何其他非 dev 的值作为第一个元素，bumpversion 就有了从该初始状态“递增”到 dev 的路径。

修正后的配置示例：

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

或者，也可以使用任意其他占位符作为初始状态，效果是相同的：

[bumpversion:part:dev]
values =
    initial_placeholder
    dev

此举使得 bumpversion 在检测到当前 dev 部分为 ""（或 initial_placeholder）时，能够将其成功递增到 dev。

完整配置示例

为了支持可选的 dev 和 build 后缀，一个完整的 bumpversion 配置示例如下：

[bumpversion]
current_version = 1.5.3
# parse 规则：定义如何从版本字符串中解析出各个部分。
# (?P\d+)\.(?P\d+)\.(?P\d+) 匹配主版本号。
# (?:-(?P.*)-(?P\d+))? 匹配可选的 -dev-build 后缀。
# ?: 表示非捕获分组，? 表示整个后缀部分是可选的。
# dev 部分使用 .* 捕获任何字符，通常在这里就是 'dev'。
parse = (?P\d+)\.(?P\d+)\.(?P\d+)(?:-(?P.*)-(?P\d+))?
# serialize 规则：定义如何将解析出的部分组合成版本字符串。
# 优先输出带 dev-build 的格式，如果 dev 或 build 部分不存在，则尝试第二个格式。
serialize =
    {major}.{minor}.{patch}-{dev}-{build}
    {major}.{minor}.{patch}

[bumpversion:part:dev]
# values 列表：第一个值 "" 作为初始状态，允许从无 dev 状态递增到 dev。
values =
    ""
    dev

[bumpversion:part:build]
# build 部分的起始值为 1。
first_value = 1

操作示例与流程

假设 current_version 初始为 1.5.3，以下是常见的操作流程：

1. 从基础版本到开发版本: 当你需要从一个标准版本（如 1.5.3）开始一个开发构建时，可以直接递增 dev 部分。由于 dev 部分的 values 列表中包含 ""，bumpversion 会将其从 "" 递增到 dev。同时，build 部分（如果被 serialize 规则激活）会自动重置为 first_value。 执行命令：

   bumpversion dev

   current_version 将变为 1.5.3-dev-1。

2. 递增开发构建号: 在开发过程中，你可能需要多次发布开发构建。此时，只需递增 build 部分：

   bumpversion build

   如果当前是 1.5.3-dev-1，执行后将变为 1.5.3-dev-2。

3. 递增补丁版本并移除开发标识: 当开发阶段完成，准备发布正式版本时，通常会递增一个更高层级的版本部分（如 patch、minor 或 major）。此时，bumpversion 会根据 serialize 规则自动选择不包含 dev 和 build 的格式。 执行命令：

   bumpversion patch

   如果当前是 1.5.3-dev-2，执行后将变为 1.5.4。

注意事项

• 非循环性: bumpversion 的版本部分递增是非循环的。一旦 dev 从 "" 递增到 dev，它就不会再自动回到 "" 状态。如果需要移除 dev 标识，通常是通过递增一个更高层级的版本部分（如 patch、minor、major），此时 serialize 规则会选择不包含 dev 的格式。
• parse 和 serialize 的匹配逻辑: serialize 列表中的格式是按顺序尝试的。bumpversion 会尝试匹配第一个能完全序列化当前版本所有部分的格式。当 dev 部分存在时，会匹配 {major}.{minor}.{patch}-{dev}-{build}。当 dev 部分不存在（或因递增更高层级版本而被清除）时，则会匹配 {major}.{minor}.{patch}。
• build 部分的重置: 每次 dev 部分发生变化（例如从 "" 变为 dev），或者 patch 等更高层级版本递增导致 dev 被移除时，如果 build 部分在 serialize 规则中被激活，它都会被重置为其 first_value。

总结

通过巧妙地在 bumpversion 的版本部分 values 列表中引入一个初始占位符（如空字符串 ""），可以有效解决可选版本后缀（如 dev）的递增问题。这种方法不仅规避了 ValueError，还为项目版本管理带来了更大的灵活性，使得开发团队能够根据需要轻松地在标准版本和带有特定标识的开发版本之间切换，从而更好地支持持续集成和发布流程。掌握此配置技巧，将大大提升版本管理的效率和准确性。