Skip to content

Commit b6c624b

Browse files
arturcicarturcic
committed
feat: separate semantic version and commit count sources
1 parent bd1f303 commit b6c624b

68 files changed

Lines changed: 963 additions & 77 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/diagrams/version-calculation.mmd‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,8 @@ sequenceDiagram
66

77
Next->>Base: GetBaseVersion
88
Note right of Base: Determine the base version
9-
Base-->>Next: 2.0.0 at 25e4ba
9+
Base-->>Next: Semantic baseline 2.0.0 and its provenance
10+
Next->>Next: Select counting anchor independently
1011

1112
alt Base version allows increment
1213
Config->>Next: Branch increment strategy (patch)
@@ -23,7 +24,7 @@ sequenceDiagram
2324
Note right of Next: 2.0.1-alpha.1
2425
end
2526

26-
Next->>Metadata: Context
27-
Metadata-->>Next: Commit count and branch/SHA metadata
27+
Next->>Metadata: Semantic provenance and counting anchor
28+
Metadata-->>Next: Count from anchor, both sources, and current branch/SHA metadata
2829
Next->>Next: Apply commit count and metadata
2930
Note right of Next: 2.0.1-alpha.1+10

‎docs/input/docs/migration/v6-to-v7.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,16 @@ macOS.
4444

4545
Use `VersionSourceDistance` instead; it has the same value.
4646

47+
## Separate semantic and counting sources
48+
49+
Five additive output variables distinguish semantic provenance from counting: `SemVerSourceSemVer`, `SemVerSourceSha`, `SemVerSourceIncrement`, `CommitCountSourceSha`, and `CommitCountSourceDistance`. They are available in JSON, custom formats, generated version-information files, build-server output, and MSBuild.
50+
51+
Existing `VersionSource*` fields keep their values. `VersionSourceSha` identifies the counting anchor, which may not be the artifact supplying `VersionSourceSemVer`. The legacy `VersionSourceIncrement` can be `None` after candidate resolution even when an increment was applied; new integrations should use `SemVerSourceIncrement`.
52+
53+
For the removed v6 `CommitsSinceVersionSource`, `VersionSourceDistance` remains a compatible replacement; `CommitCountSourceDistance` is the explicit name for the same count. Do not replace that count with a distance from `SemVerSourceSha`: configuration and branch-name sources have no intrinsic SHA. New nullable source fields use JSON null; textual outputs use an empty string.
54+
55+
Update strict JSON property-set consumers for the five added fields. Public source interfaces and existing constructors remain available. This change does not alter candidate ordering, version numbers, or commit counts. See [version variables](/docs/reference/variables) for a concrete example.
56+
4757
## CLI Arguments - POSIX-style syntax
4858

4959
GitVersion now uses POSIX-style command-line arguments powered by System.CommandLine.

‎docs/input/docs/reference/custom-formatting.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,18 @@ output:
5151
custom-version-format: '{env:ANDROID_VERSION_CODE}'
5252
```
5353
54+
## Source variables
55+
56+
Use `CommitCountSourceDistance` when formatting the count, and `SemVerSourceSemVer` or `SemVerSourceIncrement` when describing the selected semantic baseline:
57+
58+
```yaml
59+
output:
60+
assembly-informational-format: '{SemVerSourceSemVer}-{SemVerSourceIncrement}+{CommitCountSourceDistance:000}'
61+
# Example: 5.0.0-None+002 for an external 5.0.0 baseline and two counted commits.
62+
```
63+
64+
`SemVerSourceSha` can be absent for configuration or branch-name sources; it is not a substitute for `Sha` (HEAD) or `CommitCountSourceSha` (the counting anchor). Existing `VersionSource*` format names remain available for compatibility.
65+
5466
## Overview
5567

5668
The custom formatter functionality introduces several new formatters that can be used in GitVersion configuration files and templates:

‎docs/input/docs/reference/variables.md‎

Lines changed: 24 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,8 @@ the repository history and effective configuration:
1616
"AssemblySemVer": "3.22.11.0",
1717
"BranchName": "release/3.022.011",
1818
"BuildMetaData": 88,
19+
"CommitCountSourceDistance": 7,
20+
"CommitCountSourceSha": "previous-source-commit-sha",
1921
"CommitDate": "2021-12-31",
2022
"CustomVersion": "3.22.11-beta.99",
2123
"EscapedBranchName": "release-3.022.011",
@@ -32,13 +34,16 @@ the repository history and effective configuration:
3234
"PreReleaseLabel": "beta.99",
3335
"PreReleaseLabelWithDash": "-beta.99",
3436
"SemVer": "3.22.11-beta.99",
37+
"SemVerSourceIncrement": "None",
38+
"SemVerSourceSemVer": "3.22.11",
39+
"SemVerSourceSha": null,
3540
"Sha": "28c853159a46b5a87e6cc9c4f6e940c59d6bc68a",
3641
"ShortSha": "28c8531",
3742
"UncommittedChanges": 0,
3843
"VersionSourceDistance": 7,
3944
"VersionSourceIncrement": "Minor",
4045
"VersionSourceSemVer": "3.22.11",
41-
"VersionSourceSha": "28c853159a46b5a87e6cc9c4f6e940c59d6bc68a",
46+
"VersionSourceSha": "previous-source-commit-sha",
4247
"WeightedPreReleaseNumber": 1099
4348
}
4449
```
@@ -50,7 +55,9 @@ Each property of the above JSON document is described in the below table.
5055
| `AssemblySemFileVer` | Suitable for .NET `AssemblyFileVersion`. Defaults to `Major.Minor.Patch.0`. |
5156
| `AssemblySemVer` | Suitable for .NET `AssemblyVersion`. Defaults to `Major.Minor.0.0` to allow the assembly to be hotfixed without breaking existing applications that may be referencing it. |
5257
| `BranchName` | The name of the checked out Git branch. |
53-
| `BuildMetaData` | The build metadata, usually representing number of commits since the `VersionSourceSha`. Despite its name, will not increment for every build. |
58+
| `BuildMetaData` | The build metadata, usually representing number of commits since the `CommitCountSourceSha`. Despite its name, will not increment for every build. |
59+
| `CommitCountSourceDistance` | Number of non-ignored commits reachable from HEAD but not from the counting anchor. A null anchor counts all reachable history. |
60+
| `CommitCountSourceSha` | SHA of the counting anchor, or JSON null when counting all reachable history. |
5461
| `CommitDate` | The ISO-8601 formatted date of the commit identified by `Sha`. |
5562
| `CustomVersion` | A custom version configured with `custom-version-format`. Empty when no format is configured. |
5663
| `EscapedBranchName` | Equal to `BranchName`, but with `/` replaced with `-`. |
@@ -67,20 +74,31 @@ Each property of the above JSON document is described in the below table.
6774
| `PreReleaseLabel` | The full pre-release label, including the `PreReleaseNumber` when present. |
6875
| `PreReleaseLabelWithDash` | The pre-release label prefixed with a dash. |
6976
| `SemVer` | The semantic version number, including `PreReleaseLabelWithDash` for pre-release version numbers. |
77+
| `SemVerSourceIncrement` | Final increment relative to the semantic baseline: `None`, `Patch`, `Minor`, or `Major`. |
78+
| `SemVerSourceSemVer` | Baseline version supplied by the selected artifact or derivation. Mainline may use a folded baseline rather than a literal tag value. |
79+
| `SemVerSourceSha` | SHA associated with the semantic source; JSON null for external sources such as configuration or a branch name. |
7080
| `Sha` | The SHA of the Git commit. |
7181
| `ShortSha` | The `Sha` limited to 7 characters. |
7282
| `UncommittedChanges` | The number of uncommitted changes present in the repository. |
73-
| `VersionSourceDistance` | The number of commits since the version source. |
74-
| `VersionSourceIncrement` | The increment strategy used for the version calculation. Possible values: `None`, `Patch`, `Minor`, `Major`. |
75-
| `VersionSourceSemVer` | The semantic version of the commit used as version source. |
76-
| `VersionSourceSha` | The SHA of the commit used as version source. |
83+
| `VersionSourceDistance` | Compatibility alias for `CommitCountSourceDistance`. |
84+
| `VersionSourceIncrement` | Legacy increment metadata, preserved for compatibility. Prefer `SemVerSourceIncrement`; the legacy field can be `None` even when an increment was applied. |
85+
| `VersionSourceSemVer` | Legacy semantic baseline. It need not correspond to `VersionSourceSha`; prefer `SemVerSourceSemVer`. |
86+
| `VersionSourceSha` | Legacy counting-anchor SHA. Prefer `CommitCountSourceSha`, which represents an absent anchor as null. |
7787
| `WeightedPreReleaseNumber` | A summation of branch specific `pre-release-weight` and the `PreReleaseNumber`. Can be used to obtain a monotonically increasing version number across the branches. |
7888

7989
Depending on how and in which context GitVersion is executed (for instance
8090
within a [supported build server][build-servers]), the above version variables
8191
may be exposed automatically as **environment variables** in the format
8292
`GitVersion_FullSemVer`.
8393

94+
## Semantic and counting sources
95+
96+
The semantic source and counting anchor can differ. With a `1.0.0` tag followed by one commit and `calculation.next-version: 5.0.0`, the semantic baseline is `5.0.0` and `SemVerSourceSha` is null, while `CommitCountSourceSha` points to the `1.0.0` tag and `CommitCountSourceDistance` is 1. A `release/5.0.0` branch name can supply the same external baseline.
97+
98+
The distance remains available when a deployment mode incorporates the count into the pre-release number and clears `BuildMetaData`. On a selected tag at HEAD, both source SHAs are HEAD and distance is zero. `Sha` and `ShortSha` always identify the current commit.
99+
100+
See [calculation strategies](/docs/reference/version-sources) for selection and counting rules. Missing source values are JSON null in the new fields; textual outputs such as environment variables and MSBuild properties use empty strings.
101+
84102
## Formatting Variables
85103

86104
GitVersion variables can be formatted using C# format strings. See [Format Strings](/docs/reference/custom-formatting) for details.

‎docs/input/docs/reference/version-sources.md‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,12 +20,24 @@ Strategies are selected with the [`strategies` configuration setting](/docs/refe
2020

2121
## Selection and increments
2222

23-
The order of entries in `strategies` is not a priority list. GitVersion evaluates candidates and selects a next version with a corresponding version source. Fallback is deferred until other strategies have been considered.
23+
The order of entries in `strategies` is not a priority list. GitVersion evaluates candidates and selects a next version, preserving its semantic source separately from the commit-count anchor. Fallback is deferred until other strategies have been considered.
2424

2525
Do not interpret a source as “always increments” or “never increments” without the relevant branch configuration. Tagged commits, merge handling, increment inheritance, and deployment mode affect the outcome.
2626

2727
For the sequence of operations, see [how versions are calculated](/docs/learn/how-it-works).
2828

29+
## Semantic source and commit-count source
30+
31+
The **semantic source** supplies the baseline version and its final increment. Tags and merge messages have associated commits. Configuration values and branch names are external sources: they do not intrinsically belong to a commit. Mainline can fold several operations into a derived baseline while retaining its source provenance. The source is not a detector for every commit that contains a version-bump message.
32+
33+
The **commit-count source** anchors the count of commits reachable from the current commit, excluding commits reachable from the anchor and applying the configured ignore filters. This is a graph count, not first-parent distance or a count of builds. A null anchor counts all reachable, non-ignored history.
34+
35+
GitVersion compares candidates by their incremented semantic version. For multiple equal candidates with source commits, it selects the latest source timestamp. Otherwise the counting search prefers a commit-backed candidate by descending incremented version and then source timestamp. When the winning version is stable, pre-release base candidates are excluded from this counting search. Only when no commit-backed candidate remains does it use a null anchor. The order in `strategies` does not establish precedence.
36+
37+
For example, a `1.0.0` tag can remain the counting anchor while configuration or the branch name `release/5.0.0` supplies a `5.0.0` baseline. Replacing that anchor with the external semantic source would reset the meaning of the count. A later tag that raises the numeric version is reflected in semantic provenance without changing the selected counting anchor.
38+
39+
See the `SemVerSource*` and `CommitCountSource*` [output variables](/docs/reference/variables). The legacy `VersionSource*` fields retain their existing values for compatibility; they mix the two concepts.
40+
2941
## Existing source topics
3042

3143
The following anchors are retained for older links.

‎schemas/7.0/GitVersion.json‎

Lines changed: 39 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -27,12 +27,26 @@
2727
]
2828
},
2929
"BuildMetaData": {
30-
"description": "The build metadata, usually representing number of commits since the VersionSourceSha.",
30+
"description": "The build metadata, usually representing number of commits since the CommitCountSourceSha.",
3131
"type": [
3232
"null",
3333
"integer"
3434
]
3535
},
36+
"CommitCountSourceDistance": {
37+
"description": "The number of non-ignored commits reachable from HEAD but not from the counting anchor.",
38+
"type": [
39+
"null",
40+
"integer"
41+
]
42+
},
43+
"CommitCountSourceSha": {
44+
"description": "The commit used as the counting anchor, or null when counting all reachable history.",
45+
"type": [
46+
"null",
47+
"string"
48+
]
49+
},
3650
"CommitDate": {
3751
"description": "The ISO-8601 formatted date of the commit identified by Sha.",
3852
"type": [
@@ -145,6 +159,27 @@
145159
"string"
146160
]
147161
},
162+
"SemVerSourceIncrement": {
163+
"description": "The final increment relative to the semantic baseline: None, Patch, Minor or Major.",
164+
"type": [
165+
"null",
166+
"string"
167+
]
168+
},
169+
"SemVerSourceSemVer": {
170+
"description": "The semantic baseline supplied by the selected artifact or derivation.",
171+
"type": [
172+
"null",
173+
"string"
174+
]
175+
},
176+
"SemVerSourceSha": {
177+
"description": "The semantic source commit SHA, or null for external sources such as configuration or a branch name.",
178+
"type": [
179+
"null",
180+
"string"
181+
]
182+
},
148183
"Sha": {
149184
"description": "The SHA of the Git commit.",
150185
"type": [
@@ -167,7 +202,7 @@
167202
]
168203
},
169204
"VersionSourceDistance": {
170-
"description": "The number of commits since the version source.",
205+
"description": "Compatibility alias for CommitCountSourceDistance.",
171206
"type": [
172207
"null",
173208
"integer"
@@ -181,14 +216,14 @@
181216
]
182217
},
183218
"VersionSourceSemVer": {
184-
"description": "The semantic version of the commit used as version source.",
219+
"description": "Legacy semantic baseline; it need not come from VersionSourceSha. Prefer SemVerSourceSemVer.",
185220
"type": [
186221
"null",
187222
"string"
188223
]
189224
},
190225
"VersionSourceSha": {
191-
"description": "The SHA of the commit used as version source.",
226+
"description": "Compatibility alias for CommitCountSourceSha.",
192227
"type": [
193228
"null",
194229
"string"

‎src/GitVersion.Core.Tests/VersionCalculation/Approved/JsonVersionBuilderTests.Json.approved.txt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
"AssemblySemVer": "1.2.0.0",
44
"BranchName": "feature1",
55
"BuildMetaData": 5,
6+
"CommitCountSourceDistance": 5,
7+
"CommitCountSourceSha": "versionSourceSha",
68
"CommitDate": "2014-03-06",
79
"CustomVersion": "",
810
"EscapedBranchName": "feature1",
@@ -19,6 +21,9 @@
1921
"PreReleaseLabel": "unstable.4",
2022
"PreReleaseLabelWithDash": "-unstable.4",
2123
"SemVer": "1.2.0-unstable.4",
24+
"SemVerSourceIncrement": "None",
25+
"SemVerSourceSemVer": null,
26+
"SemVerSourceSha": null,
2227
"Sha": "commitSha",
2328
"ShortSha": "commitShortSha",
2429
"UncommittedChanges": 0,

‎src/GitVersion.Core.Tests/VersionCalculation/Approved/VariableProviderTests.ProvidesVariablesInContinuousDeliveryModeForFeatureBranch.approved.txt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
"AssemblySemVer": "1.2.3.0",
44
"BranchName": "feature/123",
55
"BuildMetaData": 5,
6+
"CommitCountSourceDistance": 5,
7+
"CommitCountSourceSha": "versionSourceSha",
68
"CommitDate": "2014-03-06",
79
"CustomVersion": "",
810
"EscapedBranchName": "feature-123",
@@ -19,6 +21,9 @@
1921
"PreReleaseLabel": "",
2022
"PreReleaseLabelWithDash": "",
2123
"SemVer": "1.2.3",
24+
"SemVerSourceIncrement": "None",
25+
"SemVerSourceSemVer": null,
26+
"SemVerSourceSha": null,
2227
"Sha": "commitSha",
2328
"ShortSha": "commitShortSha",
2429
"UncommittedChanges": 0,

‎src/GitVersion.Core.Tests/VersionCalculation/Approved/VariableProviderTests.ProvidesVariablesInContinuousDeliveryModeForFeatureBranchWithCustomAssemblyInfoFormat.approved.txt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
"AssemblySemVer": "1.2.3.0",
44
"BranchName": "feature/123",
55
"BuildMetaData": 5,
6+
"CommitCountSourceDistance": 5,
7+
"CommitCountSourceSha": "versionSourceSha",
68
"CommitDate": "2014-03-06",
79
"CustomVersion": "",
810
"EscapedBranchName": "feature-123",
@@ -19,6 +21,9 @@
1921
"PreReleaseLabel": "",
2022
"PreReleaseLabelWithDash": "",
2123
"SemVer": "1.2.3",
24+
"SemVerSourceIncrement": "None",
25+
"SemVerSourceSemVer": null,
26+
"SemVerSourceSha": null,
2227
"Sha": "commitSha",
2328
"ShortSha": "commitShortSha",
2429
"UncommittedChanges": 0,

‎src/GitVersion.Core.Tests/VersionCalculation/Approved/VariableProviderTests.ProvidesVariablesInContinuousDeliveryModeForPreRelease.approved.txt‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,8 @@
33
"AssemblySemVer": "1.2.3.0",
44
"BranchName": "develop",
55
"BuildMetaData": 5,
6+
"CommitCountSourceDistance": 5,
7+
"CommitCountSourceSha": "versionSourceSha",
68
"CommitDate": "2014-03-06",
79
"CustomVersion": "",
810
"EscapedBranchName": "develop",
@@ -19,6 +21,9 @@
1921
"PreReleaseLabel": "unstable.4",
2022
"PreReleaseLabelWithDash": "-unstable.4",
2123
"SemVer": "1.2.3-unstable.4",
24+
"SemVerSourceIncrement": "None",
25+
"SemVerSourceSemVer": null,
26+
"SemVerSourceSha": null,
2227
"Sha": "commitSha",
2328
"ShortSha": "commitShortSha",
2429
"UncommittedChanges": 0,

0 commit comments

Comments
 (0)