Using Calendar Versioning (CalVer)¶
Calendar Versioning (CalVer) is a versioning scheme that uses a date-based version number.
For this example, we will use the following format: YYYY.MM.DD.patch
. It will yield numbers like:
2022.2.1
for the first patch of February 1, 20222022.2.1.1
for the second patch of February 1, 2022
Initial configuration¶
[tool.bumpversion]
current_version = "2024.3.1.4"
parse = """(?x) # Verbose mode
(?P<release> # The release part
(?:[1-9][0-9]{3})\\. # YYYY.
(?:1[0-2]|[1-9])\\. # MM.
(?:3[0-1]|[1-2][0-9]|[1-9]) # DD
)
(?:\\.(?P<patch>\\d+))? # .patch, optional
"""
serialize = ["{release}.{patch}", "{release}"]
[tool.bumpversion.parts.release]
calver_format = "{YYYY}.{MM}.{DD}"
You can look up the regular expressions for the CalVer format in the CalVer reference.
Expected behavior¶
You can find out more about the logic behind the CalVer incrementing in the CalVer reference.
Bumping the release resets the patch part¶
When you bump the calendar version, the patch is reset to 0 even if the release did not change.
$ date -I
2024-03-1
$ bump-my-version show-bump
2024.3.1.4 ── bump ─┬─ release ─ 2024.3.1
╰─ patch ─── 2024.3.1.5
The next day:
$ date -I
2024-03-2
$ bump-my-version show-bump
2024.3.1.4 ── bump ─┬─ release ─ 2024.3.2
╰─ patch ─── 2024.3.2
The result of a bump to patch depends on the date¶
Calendar Versioned parts are updated with every bump, regardless of the part being bumped. If you are bumping the version within the same time period (in this example, the same day), the release
part will not change. So bumping the patch
part will increment the patch
part only.
$ date -I
2024-03-1
$ bump-my-version show-bump
2024.3.1.4 ── bump ─┬─ release ─ 2024.3.1
╰─ patch ─── 2024.3.1.5
However, if you bump the version on the next day, the release
part will also be updated.
$ date -I
2024-03-2
$ bump-my-version show-bump
2024.3.1.4 ── bump ─┬─ release ─ 2024.3.2
╰─ patch ─── 2024.3.2