[Bug] GitVersion generated version number is not sequential but increases by "CommitsSinceVersionSource" on each commit

[klachoo]

Hi. This report is perhaps not quite a bug report but rather a question which I could not find an answer for hence I am posting it here.

I have recently took over a project (a C# class library) which had a classic (ie. GUI based) Azure DevOps build pipeline which used "GitVersion@5" task in it.
The project uses GitFlow branching strategy (with default config ie. "git flow init -d").
NuGet package "GitVersion.MsBuild" (latest version available ie. at the time being "5.6.11") is used by the project as well to automatically stamp the built DLL files with the generated version information.

I have decided to move over to a YAML based pipeline and on that occasion I also wanted to move to latest version of GitVersion tasks (ie. "gitversion/setup@0" and "gitversion/execute@0") considering "GitVersion@5" is now obsolete.
The build pipeline produces some artifacts ie. NuGet packages.

The GitVersion tool uses a default config which was saved to "GitVersion.yml" file (see attachments in this issue).
My YAML build pipeline works as such however I am both a bit confused and curious why I am getting the version number that I get.
The case is that on each and every single commit I make to the development branch the version number calculated by GitVersion is incremented by exactly the amount indicated by GitVersion's own variable "CommitsSinceVersionSource".
For instance my current version is "0.1.0-ALPHA.483", then a single commit is done to development branch and the next build has version of "0.1.0-ALPHA.967".
See excerpt from file "GitVersionExecuteLog.txt"

2021-08-03T08:05:36.6993070Z     INFO [08/03/21 8:05:36:44] Found multiple base versions which will produce the same SemVer (0.1.0), taking oldest source for commit counting (Fallback base version)
2021-08-03T08:05:36.6993794Z     INFO [08/03/21 8:05:36:44] Base version used: Fallback base version: 0.1.0 with commit count source f37247d043f81426dcd6c2be9a30cf42c25a19c2
2021-08-03T08:05:36.6994392Z   INFO [08/03/21 8:05:36:44] End: Calculating base versions (Took: 215.87ms)
2021-08-03T08:05:36.6994980Z   INFO [08/03/21 8:05:36:45] 484 commits found between f37247d Added README.md, .gitignore (VisualStudio) files and f635663 Reverted the 3 commits from today.
2021-08-03T08:05:36.6995520Z   INFO [08/03/21 8:05:36:45] Skipping version increment
2021-08-03T08:05:36.6996052Z   INFO [08/03/21 8:05:36:46] 484 commits found between f37247d Added README.md, .gitignore (VisualStudio) files and f635663 Reverted the 3 commits from today.
2021-08-03T08:05:36.6996652Z   INFO [08/03/21 8:05:36:46] Begin: Getting version tags from branch 'refs/heads/develop'.
2021-08-03T08:05:36.6997169Z   INFO [08/03/21 8:05:36:49] End: Getting version tags from branch 'refs/heads/develop'. (Took: 28.02ms)
2021-08-03T08:05:36.6997674Z   INFO [08/03/21 8:05:36:50] Begin: Creating dictionary
2021-08-03T08:05:36.6998111Z   INFO [08/03/21 8:05:36:51] End: Creating dictionary (Took: 5.84ms)
2021-08-03T08:05:36.6998696Z   INFO [08/03/21 8:05:36:51] Begin: Storing version variables to cache file D:\a\1\s\.git\gitversion_cache\B22FCEF164AF3C9CDFC6CA44E6AAC90371A0BF4E.yml
2021-08-03T08:05:36.6999558Z   INFO [08/03/21 8:05:36:55] End: Storing version variables to cache file D:\a\1\s\.git\gitversion_cache\B22FCEF164AF3C9CDFC6CA44E6AAC90371A0BF4E.yml (Took: 47.84ms)
2021-08-03T08:05:36.7000159Z Executing GenerateSetVersionMessage for 'AzurePipelines'.
2021-08-03T08:05:36.7456306Z Executing GenerateBuildLogOutput for 'AzurePipelines'.
2021-08-03T08:05:36.7505408Z {
2021-08-03T08:05:36.7505650Z   "Major": 0,
2021-08-03T08:05:36.7505913Z   "Minor": 1,
2021-08-03T08:05:36.7506149Z   "Patch": 0,
2021-08-03T08:05:36.7506438Z   "PreReleaseTag": "alpha.967",
2021-08-03T08:05:36.7506749Z   "PreReleaseTagWithDash": "-alpha.967",
2021-08-03T08:05:36.7507057Z   "PreReleaseLabel": "alpha",
2021-08-03T08:05:36.7507385Z   "PreReleaseLabelWithDash": "-alpha",
2021-08-03T08:05:36.7507761Z   "PreReleaseNumber": 967,
2021-08-03T08:05:36.7508059Z   "WeightedPreReleaseNumber": 967,
2021-08-03T08:05:36.7508374Z   "BuildMetaData": null,
2021-08-03T08:05:36.7508689Z   "BuildMetaDataPadded": "",
2021-08-03T08:05:36.7509087Z   "FullBuildMetaData": "Branch.develop.Sha.f6356638f991eebcc338cd5edbfee3e4e75b4ed2",
2021-08-03T08:05:36.7509455Z   "MajorMinorPatch": "0.1.0",
2021-08-03T08:05:36.7509765Z   "SemVer": "0.1.0-alpha.967",
2021-08-03T08:05:36.7510057Z   "LegacySemVer": "0.1.0-alpha967",
2021-08-03T08:05:36.7510384Z   "LegacySemVerPadded": "0.1.0-alpha0967",
2021-08-03T08:05:36.7510717Z   "AssemblySemVer": "0.1.0.0",
2021-08-03T08:05:36.7511013Z   "AssemblySemFileVer": "0.1.0.0",
2021-08-03T08:05:36.7511341Z   "FullSemVer": "0.1.0-alpha.967",
2021-08-03T08:05:36.7511748Z   "InformationalVersion": "0.1.0-alpha.967+Branch.develop.Sha.f6356638f991eebcc338cd5edbfee3e4e75b4ed2",
2021-08-03T08:05:36.7512144Z   "BranchName": "develop",
2021-08-03T08:05:36.7512459Z   "EscapedBranchName": "develop",
2021-08-03T08:05:36.7512999Z   "Sha": "f6356638f991eebcc338cd5edbfee3e4e75b4ed2",
2021-08-03T08:05:36.7513338Z   "ShortSha": "f635663",
2021-08-03T08:05:36.7513632Z   "NuGetVersionV2": "0.1.0-alpha0967",
2021-08-03T08:05:36.7513942Z   "NuGetVersion": "0.1.0-alpha0967",
2021-08-03T08:05:36.7514280Z   "NuGetPreReleaseTagV2": "alpha0967",
2021-08-03T08:05:36.7514594Z   "NuGetPreReleaseTag": "alpha0967",
2021-08-03T08:05:36.7514967Z   "VersionSourceSha": "f37247d043f81426dcd6c2be9a30cf42c25a19c2",
2021-08-03T08:05:36.7515329Z   "CommitsSinceVersionSource": 484,
2021-08-03T08:05:36.7515660Z   "CommitsSinceVersionSourcePadded": "0484",
2021-08-03T08:05:36.7515995Z   "UncommittedChanges": 0,
2021-08-03T08:05:36.7516275Z   "CommitDate": "2021-08-03"
2021-08-03T08:05:36.7516534Z }
2021-08-03T08:05:36.7516815Z   INFO [08/03/21 8:05:36:65] Updating assembly info files
2021-08-03T08:05:36.7517158Z   INFO [08/03/21 8:05:36:65] Found 0 files
2021-08-03T08:05:36.7517505Z   INFO [08/03/21 8:05:36:66] Done writing 
2021-08-03T08:05:36.7579383Z ##[section]Async Command Start: Update Build Number
2021-08-03T08:05:37.0417190Z Update build number to 0.1.0-alpha.967 for build 12310
2021-08-03T08:05:37.0417513Z ##[section]Async Command End: Update Build Number
2021-08-03T08:05:37.0418869Z ##[section]Finishing: GitVersion execute

Is this behavior standard and by-design or is it due to my current configuration of GitVersion?
What I would rather have is the version number to be incremented solely by one on each and every commit to the development branch so from "0.1.0-ALPHA.483" I would like to go to "0.1.0-ALPHA.484".

The current behavior results in version numbers (and the resulting build number and produced NuGet package artifacts) not being exactly sequential.

I am attaching the following files to the report
(postfixed with ".txt" as some of the file types are apparently not accepted by GitHub as attachments):

• azure-pipelines.yml.txt
• GitVersion.yml.txt
• LogGitVersionOutput.txt
• UpdateBuildNumber.ps1.txt
• GitVersionExecuteLog.txt

I am willing to provide more details/other config files if/when needed.
Any clarifications for the above described situation will be appreciated. Thanks in advance.

Expected Behavior

On each and every single commit I make to the development branch the version number should be incremented solely by one so from "0.1.0-ALPHA.483" I would like to go to "0.1.0-ALPHA.484".

Actual Behavior

On each and every single commit I make to the development branch the version number calculated by GitVersion is incremented by exactly the amount indicated by GitVersion's own variable "CommitsSinceVersionSource".

Possible Fix

N.A.

Steps to Reproduce

N.A.

Context

I would like to have an exact sequential version/build number which makes it easier to get and overview over what was built when.

Your Environment

AzureDevOps, vmImage: windows-2019

[asbjornu]

GitVersion doesn't handle version numbers below 1.0.0 very well. Once you reach version 1.0.0, the subsequent alpha versions should increment much more predictably.

[wsy-cloud]

I can confirm the same strange numbering for the numbers above 1.0.0, but only if the tags with newly calculated versions become applied to the commits: 1, 3, 6, 10, and so on.
(I was just about to create a new issue to report this, but found this one, and it seems it's the same problem).

We use ContinuousDeployment mode for our dev branch. When running GitVersion for subsequent commits (only calculating, i.e. without applying the tags with these versions), we get the clean sequence 1, 2, 3, 4, and so on - as expected. For each commit, the number equals the value of CommitsSinceVersionSource. The numbers increment by 1.
But for trackability and compliance, for all the permanent branches, we apply the tag with the newly calculated version on the given commit. If we do so on our dev branch, we see the sequence 1, 3, 6, 10, and so on. It means that if there is a tag on the previous commit, holding some number in the suffix, then for the next (latest) commit GitVersion uses a mathematical sum of the number from the previous tag, and the value of CommitsSinceVersionSource (instead of CommitsSinceVersionSource only, as in the previously mentioned case without applying the tags).

The scenario with only calculating, i.e. without applying the tags (clean sequence, we like it):

• On the latest commit, we have a tag 1.0.39.
• Then we have a new commit, number 1, The calculated version is now 1.0.39-alpha.1.
• Then we have a new commit, number 2, The calculated version is now 1.0.39-alpha.2.
• Then we have a new commit, number 3, The calculated version is now 1.0.39-alpha.3.
• Then we have a new commit, number 4, The calculated version is now 1.0.39-alpha.4.

The scenario with applying the tags (resulting in unexpected sequence, we don't like it):

• On the latest commit, we have a tag 1.0.39.
• Then we have a new commit, number 1, The calculated version is now 1.0.39-alpha.1.
• Running GitVersion again, the calculated version is still 1.0.39-alpha.1, good.
• We apply the tag 1.0.39-alpha.1 to commit number 1.
• Then we have a new commit, number 2, The calculated version is now 1.0.39-alpha.3. The suffix is 3, because it is calculated as the sum of the number from the previous tag (1) plus the value of CommitsSinceVersionSource (2).
• We apply the tag 1.0.39-alpha.3 to commit number 2.
• Then we have a new commit, number 3, The calculated version is now 1.0.39-alpha.6. 6 = 3 + 3.
• We apply the tag 1.0.39-alpha.6 to commit number 3.
• Then we have a new commit, number 4, The calculated version is now 1.0.39-alpha.10. 10 = 6 + 4

Expected behavior

Whether we apply the tags or not, the sequence of the suffixes should be 1, 2, 3, 4, and so on.

Actual Behavior

When the versions become applied as tags on the commits, the sequence of the suffixes is 1, 3, 6, 10, and so on.

Our current workaround

We have a PowerShell script that, if relevant, replaces the "wrong" suffix with the value of CommitsSinceVersionSource.

GitVersion in use

Using GitVersion 5.9.0

[wsy-cloud]

Wonder if #3041 may be related ?

[asbjornu]

Yes, you can read the reasoning behind the current behavior in #465. I suppose the best we could do on the short term is to document this more clearly.

[armen-mobeus]

@asbjornu how about letting the users to customize the tag format themselves like letting them to use this tag pattern for example?

-<TagName>.{CommitsSinceVersionSource}

And the default could be something like this:

-<TagName>.{PreReleaseNumber}

Or just have a config option to use CommitsSinceVersionSource as PreReleaseNumber for the branch configuration?

[HHobeck]

I can tell you it is really hard to get into such issues and answer the question: Has it already been solved or not with the actual refactoring initiative!? Please provide integration tests any time. It makes life easier for the people who wants to make GitVersion stable. Thank you very much.

Maybe it has been solved with #3438. Anyway if I take the following integration test I don't see your point:

[Test]
public void ActualBehavior()
{
    var configuration = GitFlowConfigurationBuilder.New.Build();

    using var fixture = new EmptyRepositoryFixture("develop");

    fixture.MakeATaggedCommit("1.0.39");

    // ✅ succeeds as expected
    fixture.AssertFullSemver("1.0.39", configuration);

    fixture.MakeACommit();

    // ✅ succeeds as expected
    fixture.AssertFullSemver("1.1.0-alpha.1", configuration);

    fixture.MakeACommit();

    // ✅ succeeds as expected
    fixture.AssertFullSemver("1.1.0-alpha.2", configuration);

    fixture.ApplyTag("1.1.0-alpha.2");

    // ✅ succeeds as expected
    fixture.AssertFullSemver("1.1.0-alpha.2", configuration);

    fixture.MakeACommit();

    // ✅ succeeds as expected
    fixture.AssertFullSemver("1.1.0-alpha.3", configuration);
}