Skip to content

Commit 607609d

Browse files
coordtcoordt
committed
Updated the documentation
1 parent 53ee848 commit 607609d

File tree

4 files changed

+200
-0
lines changed

4 files changed

+200
-0
lines changed

‎README.md

+1
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,7 @@ Bump My Version's purpose is to:
2626
- Incrementing version numbers
2727
- serializing version numbers
2828
- parsing version numbers
29+
- supporting SemVer, CalVer, and other versioning schemes
2930
- Modify project files as part of the project's development life cycle
3031
- Work with the project's source control system
3132
- Committing changes

‎docsrc/howtos/calver.md

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# Using Calendar Versioning (CalVer)
2+
3+
Calendar Versioning (CalVer) is a versioning scheme that uses a date-based version number.
4+
5+
For this example, we will use the following format: `YYYY.MM.DD.patch`. It will yield numbers like:
6+
7+
- `2022.2.1` for the first patch of February 1, 2022
8+
- `2022.2.1.1` for the second patch of February 1, 2022
9+
10+
11+
## Initial configuration
12+
13+
```toml title=".bumpversion.toml"
14+
[tool.bumpversion]
15+
current_version = "2024.3.1.4"
16+
parse = """(?x) # Verbose mode
17+
(?P<release> # The release part
18+
(?:[1-9][0-9]{3})\\. # YYYY.
19+
(?:1[0-2]|[1-9])\\. # MM.
20+
(?:3[0-1]|[1-2][0-9]|[1-9]) # DD
21+
)
22+
(?:\\.(?P<patch>\\d+))? # .patch, optional
23+
"""
24+
serialize = ["{release}.{patch}", "{release}"]
25+
26+
[tool.bumpversion.parts.release]
27+
calver_format = "{YYYY}.{MM}.{DD}"
28+
```
29+
30+
You can look up the regular expressions for the CalVer format in the [CalVer reference](../reference/calver_reference.md).
31+
32+
## Expected behavior
33+
34+
You can find out more about the logic behind the CalVer incrementing in the [CalVer reference](../reference/calver_reference.md#calver-incrementing-logic).
35+
36+
### Bumping the release resets the patch part
37+
38+
When you bump the calendar version, the patch is reset to 0 _even if the release did not change._
39+
40+
```console title="Bumping the release resets patch"
41+
$ date -I
42+
2024-03-1
43+
$ bump-my-version show-bump
44+
2024.3.1.4 ── bump ─┬─ release ─ 2024.3.1
45+
╰─ patch ─── 2024.3.1.5
46+
```
47+
48+
The next day:
49+
50+
```console title="Bumping the release resets patch, the next day"
51+
$ date -I
52+
2024-03-2
53+
$ bump-my-version show-bump
54+
2024.3.1.4 ── bump ─┬─ release ─ 2024.3.2
55+
╰─ patch ─── 2024.3.2
56+
```
57+
58+
### The result of a bump to patch depends on the date
59+
60+
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.
61+
62+
63+
```console title="Bumping patch on the same day"
64+
$ date -I
65+
2024-03-1
66+
$ bump-my-version show-bump
67+
2024.3.1.4 ── bump ─┬─ release ─ 2024.3.1
68+
╰─ patch ─── 2024.3.1.5
69+
```
70+
71+
However, if you bump the version on the next day, the `release` part will also be updated.
72+
73+
```console title="Bumping patch on the next day"
74+
$ date -I
75+
2024-03-2
76+
$ bump-my-version show-bump
77+
2024.3.1.4 ── bump ─┬─ release ─ 2024.3.2
78+
╰─ patch ─── 2024.3.2
79+
```

‎docsrc/reference/calver_reference.md

+91
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
# Calendar versioning reference
2+
3+
## Calendar versioning codes
4+
5+
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}"`.
6+
7+
| Code | Example(s) | Comment |
8+
|--------|---------------------|-----------------------------------------------|
9+
| `YYYY` | 2000, 2001, …, 2099 | Full year |
10+
| `YY` | 0, 1, 2, …, 99 | Short year as integer |
11+
| `0Y` | 00, 01, 02, …, 99 | Short Year, zero-padded |
12+
| `MMM` | Jan, Feb, jan, fév | Month abbreviation, locale-based |
13+
| `MM` | 1, 2, …, 12 | Month as integer |
14+
| `0M` | 01, 02, …, 12 | Month, zero-padded |
15+
| `DD` | 1, 2, …, 31 | Day of month as integer |
16+
| `0D` | 01, 02, …, 31 | Day of month, zero-padded |
17+
| `JJJ` | 1, 2, 3, …, 366 | Day of year as integer |
18+
| `00J` | 001, 002, …, 366 | Day of year, zero-padded |
19+
| `Q` | 1, 2, 3, 4 | Quarter |
20+
| `WW` | 0, 1, 2, …, 53 | Week number, Monday is first day |
21+
| `0W` | 00, 01, 02, …, 53 | Week number, Monday is first day, zero-padded |
22+
| `UU` | 0, 1, 2, …, 53 | Week number, Sunday is first day |
23+
| `0U` | 00, 01, 02, …, 53 | Week number, Sunday is first day, zero-padded |
24+
| `VV` | 1, 2, …, 53 | ISO 8601 week number as integer |
25+
| `0V` | 01, 02, …, 53 | ISO 8601 week number, zero-padded |
26+
| `GGGG` | 2000, 2001, …, 2099 | ISO 8601 week-based year |
27+
| `GG` | 0, 1, 2, …, 99 | ISO 8601 short week-based year as integer |
28+
| `0G` | 01, 02, …, 99 | ISO 8601 short week-based year, zero-padded |
29+
30+
```toml title="Example configuration"
31+
[tool.bumpversion.parts.release]
32+
calver_format = "{YYYY}.{MM}.{DD}"
33+
```
34+
35+
36+
## Parsing CalVer versions
37+
38+
Using the following chart, we can set up the version parsing:
39+
40+
| Code | Regex |
41+
|--------|-------------------------------------------------------------------|
42+
| `YYYY` | `(?:[1-9][0-9]{3})` |
43+
| `YY` | `(?:[1-9][0-9]?)` |
44+
| `0Y` | `(?:[0-9]{2})` |
45+
| `MMM` | See below |
46+
| `MM` | `(?:1[0-2]\|[1-9])` |
47+
| `0M` | `(?:1[0-2]\|0[1-9])` |
48+
| `DD` | `(?:3[0-1]\|[1-2][0-9]\|[1-9])` |
49+
| `0D` | `(?:3[0-1]\|[1-2][0-9]\|0[1-9])` |
50+
| `JJJ` | `(?:36[0-6]\|3[0-5][0-9]\|[1-2][0-9][0-9]\|[1-9][0-9]\|[1-9])` |
51+
| `00J` | `(?:36[0-6]\|3[0-5][0-9]\|[1-2][0-9][0-9]\|0[1-9][0-9]\|00[1-9])` |
52+
| `Q` | `(?:[1-4])` |
53+
| `WW` | `(?:5[0-3]\|[1-4][0-9]\|[0-9])` |
54+
| `0W` | `(?:5[0-3]\|[0-4][0-9])` |
55+
| `UU` | `(?:5[0-3]\|[1-4][0-9]\|[0-9])` |
56+
| `0U` | `(?:5[0-3]\|[0-4][0-9])` |
57+
| `VV` | `(?:5[0-3]\|[1-4][0-9]\|[1-9])` |
58+
| `0V` | `(?:5[0-3]\|[1-4][0-9]\|0[1-9])` |
59+
| `GGGG` | `(?:[1-9][0-9]{3})` |
60+
| `GG` | `(?:[0-9][0-9]?)` |
61+
| `0G` | `(?:[0-9]{2})` |
62+
63+
!!! Note "Month abbreviations"
64+
65+
The month abbreviation is locale-based. Here are some examples:
66+
67+
`(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)` for English
68+
69+
`(?:jan|fév|mar|avr|mai|jui|jui|aoû|sep|oct|nov|déc)` for French
70+
71+
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:
72+
73+
```toml
74+
[tool.bumpversion]
75+
parse = """(?x) # Verbose mode
76+
(?P<release>
77+
(?:[1-9][0-9]{3})\\. # YYYY.
78+
(?:1[0-2]|[1-9])\\. # MM.
79+
(?:3[0-1]|[1-2][0-9]|[1-9]) # DD
80+
)
81+
"""
82+
```
83+
84+
## CalVer incrementing logic
85+
86+
- CalVer version components are marked as `always_increment` by default.
87+
- When bumping a version, you specify which component to increment. It is called the target component.
88+
- When bumping a version, the components marked as `always_increment` are incremented first.
89+
- If an `always_increment` component's value changed, its dependent components are marked for reset to their default values.
90+
- If the target component is in the set of components marked for reset, the target component is reset to its default value.
91+
- 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

+29
Original file line numberDiff line numberDiff line change
@@ -506,6 +506,35 @@ When the part is reset, the value will be set to the value specified here.
506506
When this value is set to `True`, the part is not reset when other parts are incremented. Its incrementation is
507507
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.
508508

509+
### always_increment
510+
511+
::: field-list
512+
required
513+
: No
514+
515+
default
516+
: `False` (`True` if `calver_format` is set)
517+
518+
type
519+
: boolean
520+
521+
When this value is set to `True`, the part is always incremented when the version is bumped, regardless of the target part.
522+
523+
524+
### calver_format
525+
526+
::: field-list
527+
required
528+
: No
529+
530+
default
531+
: empty
532+
533+
type
534+
: string
535+
536+
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).
537+
509538
### Examples
510539

511540
=== "TOML"

0 commit comments

Comments
 (0)