Updated the documentation

README.md

@@ -26,6 +26,7 @@ Bump My Version's purpose is to:
     - Incrementing version numbers
     - serializing version numbers
     - parsing version numbers
+    - supporting SemVer, CalVer, and other versioning schemes
 - Modify project files as part of the project's development life cycle
 - Work with the project's source control system
     - Committing changes

docsrc/howtos/calver.md

@@ -0,0 +1,79 @@
+# 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
+
+```toml title=".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](../reference/calver_reference.md).
+
+## Expected behavior
+
+You can find out more about the logic behind the CalVer incrementing in the [CalVer reference](../reference/calver_reference.md#calver-incrementing-logic).
+
+### 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._
+
+```console title="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:
+
+```console title="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.
+
+
+```console title="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.
+
+```console title="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
+```

docsrc/reference/calver_reference.md

@@ -0,0 +1,91 @@
+# Calendar versioning reference
+
+## Calendar versioning codes
+
+The following table lists the available format codes for calendar versioning (CalVer) schemes. The codes can be used to define the version format in the `calver_format` configuration options. Formatting codes, surrounded by `{ }` can be combined to create a custom version format. For example, the format `YYYY.MM.DD` can be defined as `"{YYYY}.{MM}.{DD}"`.
+
+| Code   | Example(s)          | Comment                                       |
+|--------|---------------------|-----------------------------------------------|
+| `YYYY` | 2000, 2001, …, 2099 | Full year                                     |
+| `YY`   | 0, 1, 2, …, 99      | Short year as integer                         |
+| `0Y`   | 00, 01, 02, …, 99   | Short Year, zero-padded                       |
+| `MMM`  | Jan, Feb, jan, fév  | Month abbreviation, locale-based              |
+| `MM`   | 1, 2, …, 12         | Month as integer                              |
+| `0M`   | 01, 02, …, 12       | Month, zero-padded                            |
+| `DD`   | 1, 2, …, 31         | Day of month as integer                       |
+| `0D`   | 01, 02, …, 31       | Day of month, zero-padded                     |
+| `JJJ`  | 1, 2, 3, …, 366     | Day of year as integer                        |
+| `00J`  | 001, 002, …, 366    | Day of year, zero-padded                      |
+| `Q`    | 1, 2, 3, 4          | Quarter                                       |
+| `WW`   | 0, 1, 2, …, 53      | Week number, Monday is first day              |
+| `0W`   | 00, 01, 02, …, 53   | Week number, Monday is first day, zero-padded |
+| `UU`   | 0, 1, 2, …, 53      | Week number, Sunday is first day              |
+| `0U`   | 00, 01, 02, …, 53   | Week number, Sunday is first day, zero-padded |
+| `VV`   | 1, 2, …, 53         | ISO 8601 week number as integer               |
+| `0V`   | 01, 02, …, 53       | ISO 8601 week number, zero-padded             |
+| `GGGG` | 2000, 2001, …, 2099 | ISO 8601 week-based year                      |
+| `GG`   | 0, 1, 2, …, 99      | ISO 8601 short week-based year as integer     |
+| `0G`   | 01, 02, …, 99       | ISO 8601 short week-based year, zero-padded   |
+
+```toml title="Example configuration"
+[tool.bumpversion.parts.release]
+calver_format = "{YYYY}.{MM}.{DD}"
+```
+
+
+## Parsing CalVer versions
+
+Using the following chart, we can set up the version parsing:
+
+| Code   | Regex                                                             |
+|--------|-------------------------------------------------------------------|
+| `YYYY` | `(?:[1-9][0-9]{3})`                                               |
+| `YY`   | `(?:[1-9][0-9]?)`                                                 |
+| `0Y`   | `(?:[0-9]{2})`                                                    |
+| `MMM`  | See below                                                         |
+| `MM`   | `(?:1[0-2]\|[1-9])`                                               |
+| `0M`   | `(?:1[0-2]\|0[1-9])`                                              |
+| `DD`   | `(?:3[0-1]\|[1-2][0-9]\|[1-9])`                                   |
+| `0D`   | `(?:3[0-1]\|[1-2][0-9]\|0[1-9])`                                  |
+| `JJJ`  | `(?:36[0-6]\|3[0-5][0-9]\|[1-2][0-9][0-9]\|[1-9][0-9]\|[1-9])`    |
+| `00J`  | `(?:36[0-6]\|3[0-5][0-9]\|[1-2][0-9][0-9]\|0[1-9][0-9]\|00[1-9])` |
+| `Q`    | `(?:[1-4])`                                                       |
+| `WW`   | `(?:5[0-3]\|[1-4][0-9]\|[0-9])`                                   |
+| `0W`   | `(?:5[0-3]\|[0-4][0-9])`                                          |
+| `UU`   | `(?:5[0-3]\|[1-4][0-9]\|[0-9])`                                   |
+| `0U`   | `(?:5[0-3]\|[0-4][0-9])`                                          |
+| `VV`   | `(?:5[0-3]\|[1-4][0-9]\|[1-9])`                                   |
+| `0V`   | `(?:5[0-3]\|[1-4][0-9]\|0[1-9])`                                  |
+| `GGGG` | `(?:[1-9][0-9]{3})`                                               |
+| `GG`   | `(?:[0-9][0-9]?)`                                                 |
+| `0G`   | `(?:[0-9]{2})`                                                    |
+
+!!! Note "Month abbreviations"
+
+    The month abbreviation is locale-based. Here are some examples:
+
+    `(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)` for English
+
+    `(?:jan|fév|mar|avr|mai|jui|jui|aoû|sep|oct|nov|déc)` for French
+
+You can use these regular expressions to parse CalVer versions in your project. For example, the following `parse` configuration can be used to parse a version string in the format `YYYY.MM.DD` as the `release` part of the version string:
+
+```toml
+[tool.bumpversion]
+parse = """(?x)                      # Verbose mode
+    (?P<release>
+        (?:[1-9][0-9]{3})\\.         # YYYY.
+        (?:1[0-2]|[1-9])\\.          # MM.
+        (?:3[0-1]|[1-2][0-9]|[1-9])  # DD
+    )
+"""
+```
+
+## CalVer incrementing logic
+
+- CalVer version components are marked as `always_increment` by default.
+- When bumping a version, you specify which component to increment. It is called the target component.
+- When bumping a version, the components marked as `always_increment` are incremented first.
+- If an `always_increment` component's value changed, its dependent components are marked for reset to their default values.
+- If the target component is in the set of components marked for reset, the target component is reset to its default value.
+- If the target component is not in the set of components marked for reset, the target component is incremented and its dependent components are reset to their default values.

docsrc/reference/configuration.md

@@ -506,6 +506,35 @@ When the part is reset, the value will be set to the value specified here.
 When this value is set to `True`, the part is not reset when other parts are incremented. Its incrementation is
 independent of the other parts. It is useful when you have a build number in your version that is incremented independently of the actual version.
 
+### always_increment
+
+::: field-list
+    required
+    : No
+
+    default
+    : `False` (`True` if `calver_format` is set)
+
+    type
+    : boolean
+
+When this value is set to `True`, the part is always incremented when the version is bumped, regardless of the target part.
+
+
+### calver_format
+
+::: field-list
+    required
+    : No
+
+    default
+    : empty
+
+    type
+    : string
+
+The `calver_format` is a string that specifies the format of the version part. It is used to determine the next value when bumping the version. The format is a string that uses the placeholders defined in the [CalVer reference](calver_reference.md#calver-format).
+
 ### Examples
 
 === "TOML"