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]

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?

[asbjornu]

I like the idea. What do you think about defining a more versatile custom-version-format property which would be exposed as a CustomVersion output property by GitVersion?

[HHobeck]

What do you mean with CustomVersion!? Do you have an example?

Let's say you have the following git history:

* commit d512752c06d761a8fe8d42158797e2f8123d5504 (HEAD -> feature/next)
|     B
* commit 32dd297268c38601eda4fe34ca536f92fe715454
|     A
* commit c7e5191d45c6c1277444d5727726d021a5389eb8 (tag: 1.0.0, master)
      Initial Commit

with configuration A:

workflow: GitFlow/v1
branches:
  feature:
    mode: ManualDeployment

gitversion would output 1.0.1-next.1+2:

{
  "AssemblySemFileVer": "1.0.1.0",
  "AssemblySemVer": "1.0.1.0",
  "BranchName": "feature/next",
  "BuildMetaData": 2,
  "CommitDate": "2024-11-21",
  "CommitsSinceVersionSource": 2,
  "EscapedBranchName": "feature-next",
  "FullBuildMetaData": "2.Branch.feature-next.Sha.d512752c06d761a8fe8d42158797e2f8123d5504",
  "FullSemVer": "1.0.1-next.1+2",
  "InformationalVersion": "1.0.1-next.1+2.Branch.feature-next.Sha.d512752c06d761a8fe8d42158797e2f8123d5504",
  "Major": 1,
  "MajorMinorPatch": "1.0.1",
  "Minor": 0,
  "Patch": 1,
  "PreReleaseLabel": "next",
  "PreReleaseLabelWithDash": "-next",
  "PreReleaseNumber": 1,
  "PreReleaseTag": "next.1",
  "PreReleaseTagWithDash": "-next.1",
  "SemVer": "1.0.1-next.1",
  "Sha": "d512752c06d761a8fe8d42158797e2f8123d5504",
  "ShortSha": "d512752",
  "UncommittedChanges": 0,
  "VersionSourceSha": "c7e5191d45c6c1277444d5727726d021a5389eb8",
  "WeightedPreReleaseNumber": 30001
}

with configuration B:

workflow: GitFlow/v1
branches:
  feature:
    mode: ContinuousDelivery

gitversion would output 1.0.1-next.2:

{
  "AssemblySemFileVer": "1.0.1.0",
  "AssemblySemVer": "1.0.1.0",
  "BranchName": "feature/next",
  "BuildMetaData": null,
  "CommitDate": "2024-11-21",
  "CommitsSinceVersionSource": 2,
  "EscapedBranchName": "feature-next",
  "FullBuildMetaData": "Branch.feature-next.Sha.d512752c06d761a8fe8d42158797e2f8123d5504",
  "FullSemVer": "1.0.1-next.2",
  "InformationalVersion": "1.0.1-next.2+Branch.feature-next.Sha.d512752c06d761a8fe8d42158797e2f8123d5504",
  "Major": 1,
  "MajorMinorPatch": "1.0.1",
  "Minor": 0,
  "Patch": 1,
  "PreReleaseLabel": "next",
  "PreReleaseLabelWithDash": "-next",
  "PreReleaseNumber": 2,
  "PreReleaseTag": "next.2",
  "PreReleaseTagWithDash": "-next.2",
  "SemVer": "1.0.1-next.2",
  "Sha": "d512752c06d761a8fe8d42158797e2f8123d5504",
  "ShortSha": "d512752",
  "UncommittedChanges": 0,
  "VersionSourceSha": "c7e5191d45c6c1277444d5727726d021a5389eb8",
  "WeightedPreReleaseNumber": 30002
}

From my understanding the author wants to use an algorithm to overwrite the CommitsSinceVersionSource. Please keep in mind that the CommitsSinceVersionSource will be used as a basis to calculate other variables which are dependent on other settings (e.g. ManualDeployment vs. ContinuousDelivery mode).

[asbjornu]

I was thinking CustomVersion would be more flexible than just allowing to override CommitsSinceVersionSource. Also, overriding CommitsSinceVersionSource with something like github.run_number doesn't make sense, since "commits since version source" should mean just that: "commits since version source". If we were to allow override of a property, I'd say it should be BuildMetadata.

However, by introducing custom-version-format and CustomVersion, people could build their own version numbers by using GitVersion's exposed version properties as well as environment variables and ensure adherence to stricter versioning schemes (such as Python's PEP440; see #2065) where characters like + isn't allowed, for instance. custom-version-format could then be set to something like this:

custom-version-format: {MajorMinorPatch}.{env:GITHUB_RUN_NUMBER ?? CommitsSinceVersionSource}

Which could result in something like this:

{
  "CustomVersion": "1.0.1.738"
}

[HHobeck]

I see your argument and I agree that CommitsSinceVersionSource should express only this and not something else. But how would you support the use case to print out a custom version dependent on the mode?

for ManualDeployment mode:

{
  "CustomVersion": "1.0.1-next.1+738"
}

for ContinuousDelivery mode:

{
  "CustomVersion": "1.0.1-next.738"
}

for ContinuousDeployment mode:

{
  "CustomVersion": "1.0.1"
}

Please notice that the mode is not a global setting and might be branch specific.

[sagedemdreisbusch]

@HHobeck thank you very much for your guidance. It was manual deployment we have been looking for. So now we will modify the config and everything is working like we want it to work 🥳