GitVersion 6.0.0 is not supported due to breaking changes

[johlju]

Problem description

There are breaking changes in GitVersion that fails builds in projects using Sampler. Workaround is to pin an older version.

Notable breaking changes are configuration properties that has changed name, and output properties (NuGetVersionV2) that no longer exist.

Configuration documentation: https://gitversion.net/docs/reference/configuration
Output variables: https://gitversion.net/docs/reference/variables

Verbose logs

You can invoke the tool using the following command: dotnet-gitversion
Tool 'gitversion.tool' (version '6.0.0') was successfully installed.
ConvertFrom-Json : Conversion from JSON failed with error: Error parsing Infinity value. Path '', line 1, position 1.
At D:\a\_temp\87ce70e7-6735-4619-b9cf-c7cfe9c66d84.ps1:5 char:41
+ $gitVersionObject = dotnet-gitversion | ConvertFrom-Json
+                                         ~~~~~~~~~~~~~~~~
+ CategoryInfo          : NotSpecified: (:) [ConvertFrom-Json], ArgumentException
+ FullyQualifiedErrorId : System.ArgumentException,Microsoft.PowerShell.Commands.ConvertFromJsonCommand
##[error]PowerShell exited with code '1'.

How to reproduce

Build a project using GitVersion v6.0.0

Expected behavior

Sampler supports v6.0.0

Current behavior

Fails if GitVersion 6.0.0 is installeed.

Suggested solution

Update all tasks and configuration (and templates) to use another property than NuGetVersionV2.

Did a quick test in another project to see what was needed when I realized that we have hardcoded NuGetVersionV2 in the tasks. This PR shows the needed config changes: viscalyx/PesterConverter#28

Also, the property used cannot contain '.' in the prerelease string since it is not supported in module manifest. 🤔

Operating system the target node is running

n/a

PowerShell version and build the target node is running

n/a

Module version used

n/a

[johlju]

Workaround is to install 5.12.0 in Azure Pipelines, e.g.:

dotnet tool install --global GitVersion.Tool --version 5.12.0

[dan-hughes]

Can use dotnet tool install --global GitVersion.Tool --version 5.* in case any updates to v5 are released.

[johlju]

As mentioned by @gaelcolas offline is that we need to pad the preview string number with zeros, e.g. 'preview0001'. This so sorting in certain NuGet repositories work as expected, it is an OData issue with NuGet. To prevent that -preview9 is assumed to be higher than -preview12.

Also, any dot (.) in the prerelease string must be removed as it is not supported in the module manifest (I might be wrong here).

This is an example from GitVersion's docs (link above):

{
    "Major": 3,
    "Minor": 22,
    "Patch": 11,
    "PreReleaseTag": "beta.99",
    "PreReleaseTagWithDash": "-beta.99",
    "PreReleaseLabel": "beta",
    "PreReleaseLabelWithDash": "-beta",
    "PreReleaseNumber": 99,
    "WeightedPreReleaseNumber": 1099,
    "BuildMetaData": 88,
    "FullBuildMetaData": "99.Branch.release/3.22.11.Sha.28c853159a46b5a87e6cc9c4f6e940c59d6bc68a",
    "MajorMinorPatch": "3.22.11",
    "SemVer": "3.22.11-beta.99",
    "AssemblySemVer": "3.22.11.0",
    "AssemblySemFileVer": "3.22.11.0",
    "InformationalVersion": "3.22.11-beta.99+88.Branch.release/3.022.011.Sha.28c853159a46b5a87e6cc9c4f6e940c59d6bc68a",
    "FullSemVer": "3.22.11-beta.99+88",
    "BranchName": "release/3.022.011",
    "EscapedBranchName": "release-3.022.011",
    "Sha": "28c853159a46b5a87e6cc9c4f6e940c59d6bc68a",
    "ShortSha": "28c8531",
    "VersionSourceSha": "28c853159a46b5a87e6cc9c4f6e940c59d6bc68a",
    "CommitsSinceVersionSource": 7,
    "CommitDate": "2021-12-31",
    "UncommittedChanges": 0
}

My thoughts:

• Build pipeline version title
  • The build pipeline should preferably use FullSemVer so that the pipeline title is unique for each build. Not tested that it works.
  • I don't see it would be necessary to pad version number here.
• Module version
  • The module version should use the properties should concatenate MajorMinorPatch + PreReleaseTag.
  • The PreReleaseTag should be padded with 4 zeros and have the . removed, e.g.:

    $prereleaseString = 'beta.99' # result from GitVersion's variable PreReleaseTag
    $match = [System.Text.RegularExpressions.Regex]::Match($prereleaseString, '(\d+)$')
    $numericValue = $match.Groups[1].Value.PadLeft(4, '0')
    $nonNumericPart = $prereleaseString.Substring(0, $match.Groups[1].Index) -replace '\.'
    $paddedPrereleaseString = "$nonNumericPart$numericValue"
    $paddedPrereleaseString

[johlju]

Maybe we should introduce a a command that has several purposes (maybe we already have one)

• Call gitversion (build script supports both gitversion and donet-gitversion)
• Return the ModuleVersion according to above
• Return the pipeline job title (semantic version + build number)
• Set the task variables for the Azure Pipelines pipeline (see azure-pipelines.yml)

The command can return different values depending on passed parameters.

[pshamus]

Another option I'm using is to add a build task to install GitVersion if needed:

param (
    # Build Configuration object
    [Parameter()]
    [System.Collections.Hashtable]
    $BuildInfo = (property BuildInfo @{ })
)

# Synopsis: Installs GitVersion as a .NET Global Tool if needed
task Install_GitVersion -if ($BuildInfo.GitVersion.Version) {
    $gitVersionAvailable = Get-Command -Name 'gitversion' -ErrorAction 'SilentlyContinue'
    $dotNetGitVersionAvailable = Get-Command -Name 'dotnet-gitversion' -ErrorAction 'SilentlyContinue'

    # If neither dotnet-gitversion nor gitversion are available, install dotnet-gitversion.
    if (-not $dotNetGitVersionAvailable -and -not $gitVersionAvailable) {
        Write-Build -Color Green -Text "Installing GitVersion $($BuildInfo.GitVersion.Version) as a .NET Global Tool"
        $null = dotnet tool install --global GitVersion.Tool --version $BuildInfo.GitVersion.Version
    }
}

Once Sampler is updated to support both versions when determining the module version, you can selectively update a given project to use 6.x, which might also include updating GitVersion.yml as the schema has changed too.

[johlju]

Another option I'm using is to add a build task to install GitVersion if needed

Downside to this is that we shouldn't change the users machine which will happen if the user runs the task locally. Currently Sampler expects correct version to be installed on the users machine. Is it possible to save it just for the project without installing it, like portable so it can be easily removed?

[johlju]

For macOS and brew users:

It is possible to run $ModuleVersion = '0.0.1' locally before build to skip GitVersion requirement if it is not installed and there is no need to build using correct version. 🤔

I currently need to do that on my macOS which updated to v6, where it is not possible to revert to 5.x version using brew (I can't find a way for GitVersion at least).

[pshamus]

If you install the tool in a custom path (which I am currently doing), you can invoke from there. So maybe the tool is installed in output, that way it's not installed on the user's machine outside of each repository. You'd need to update the build scripts to invoke dotnet-gitversion from the custom path. But it's a nice way to not rely on the pipeline to determine what version to use so you can reproduce the behavior locally. It's very similar to how the build process downloads the necessary modules.

[johlju]

So maybe the tool is installed in output, that way it's not installed on the user's machine outside of each repository.

I wonder what is required to get dotnet working on a stock *nix, macOS and Windows. 🤔 Maybe installing PowerShell is enough for dotnet tool to work? I think your suggest could work, only adding a task if the user says in the template that GtVersion should be used to handle versioning. 🤔