Skip to content

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, 2022
  • 2022.2.1.1 for the second patch of February 1, 2022

Initial configuration

.bumpversion.toml
[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.

Bumping the release resets patch
$ 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:

Bumping the release resets patch, 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.

Bumping patch on the same day
$ 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.

Bumping patch on 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