Extend GitVersion to Count Builds within a Version

[sagedemdreisbusch]

Description:

Currently, GitVersion defaults to counting the number of commits since the last tag to generate the build number within a version. For our project, it would be helpful if GitVersion could alternatively count the number of builds within a version, independently of the number of commits. This would allow us to have consecutive build numbers for each new version without relying on commit count.

Requirement:

Implement an option in GitVersion that allows build numbering based on the count of builds within a specific version rather than on the number of commits since the last tag.
This option should only expose another variable with the build count so it can be used in the assemblyFileVersionFormat option.

Examples:

At the moment when starting a version you start with zero commits (e.g. 1.2.0.0) after committing three times it will result with an inrease number of 3 when using the PreReleaseNumber Option (1.2.0.3). When having another 4 commits we have a count of 7.
What our suggestion is: First Build 1.2.0.0, second build 1.2.0.1, third build 1.2.0.2, ...
So it is like adding another counter as Major, Minor, patch but with the name Revision or BuildCount maybe?

Benefits:

• Facilitates traceability and consistency in build numbering for projects that prefer build counting.
• Increases GitVersion's flexibility to meet various project needs regarding build numbering.

Acceptance Criteria:

• A new configuration option exists in GitVersion that allows the build number to be based on the number of builds per version.
• The current functionality of counting commits for the build number remains intact and is not impacted by the new functionality.

Additional Information:

If similar approaches or suggestions exist, it would be helpful to discuss them to find the best possible solution.

[HHobeck]

On https://semver.org/ following is written:

Semantic Versioning 2.0.0
Summary
Given a version number MAJOR.MINOR.PATCH, increment the:

MAJOR version when you make incompatible API changes
MINOR version when you add functionality in a backward compatible manner
PATCH version when you make backward compatible bug fixes
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

When triggering on commit twice the generated artefacts should be equivalent and have the same semantic version. We are generating this version based on the repository state. The only way I see is changing the assembly-informational-format property in the configuration and using the InformationalVersion output variable:

workflow: GitFlow/v1
assembly-informational-format: '{Major}.{Minor}.{Patch}.{env:CI_JOB_ID ?? 0}'

Link[1]: Version Variables

[thomassvensen]

Hi @alessiop-forsta
We had exactly the same challenge that you have - our developers frequently squash commits in order to have a cleaner git history, and that would often make the feature builds non-unique. A related problem was that the latest version would not always "look latest", since it may have a smaller commit number than an earlier build.

Our solution was to take the timestamp of the latest commit and base-36 encode it, and then zero-pad it, and use that as the unique identifier. Here is how you can calculate it:

        var startDate = new DateTime(year: 2024, month: 1, day: 1);
        var timeDifference = latestCommit.Committer.When - startDate;
        var minutesPassed = timeDifference.TotalMinutes;

        const string Chars = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";
        var base36 = Chars.Length;
        var result = string.Empty;

        while (minutesPassed > 0)
        {
            var remainder = (int)(minutesPassed % base36);
            result = Chars[remainder] + result;
            minutesPassed /= base36;
        }

        // The first 6 digits is sufficient for 100 years
        var alwaysIncreasingUniqueBuildId = result[^6..];

I hope that may be useful inspiration. By the way, another useful benefit is that it will be identical whether run local or in a CI/CD pipeiline

[alessiop-forsta]

Thanks everyone for the advice, it was very helpful :-)

[HHobeck]

Our solution was to take the timestamp of the latest commit and base-36 encode it, and then zero-pad it, and use that as the unique identifier.

@thomassvensen: How does this algorithm interact with GitVersion? How would you use this unique build ID in the semantic versioning scheme? You say it is used also on local builds. Does this mean you are using GitVersion.MsBuild package (which is I think not supported for Visual Studio 2022 and dotnet core 8.0)?

[thomassvensen]

Our solution was to take the timestamp of the latest commit and base-36 encode it, and then zero-pad it, and use that as the unique identifier.

@thomassvensen: How does this algorithm interact with GitVersion? How would you use this unique build ID in the semantic versioning scheme? You say it is used also on local builds. Does this mean you are using GitVersion.MsBuild package (which is I think not supported for Visual Studio 2022 and dotnet core 8.0)?

Yes, I realize I did not tell the full story. Currently, we do this outside GitVersion itself. We generate a version string where most elements come from GitVersion, and just pad this at the end. Something like this:

        var semVer = $"{_gitVersionResult.MajorMinorPatch}-{_gitVersionResult.EscapedBranchName}.{alwaysIncreasingUniqueBuildId}";

But it would of course be better to have it natively available from GitVersion. Perhaps I should consider making a PR for it?

[HHobeck]

I see the use case and think it might be a good idea to have an mechanism in place to pass in the CommitsSinceVersionSource from outside. At the moment we can define this:

assembly-file-versioning-format: {Major}.{Minor}.{Patch}.{env:CI_JOB_ID ?? 0}
assembly-versioning-format: {Major}.{Minor}.{Patch}.{env:CI_JOB_ID ?? 0}
assembly-informational-format: {Major}.{Minor}.{Patch}.{env:CI_JOB_ID ?? 0}

Maybe we can introduce a new configuration commits-since-version-source-format: {env:CI_JOB_ID ?? CommitsSinceVersionSource}.

@asbjornu: Any ideas?