Nerdbank.gitversioning: Allow disabling "g" prefix for commit hash in version number

[akoeplinger]

I've had multiple folks (including myself) be confused about the g in front of the commit sha of a version number like 16.0.40-preview+ge6c3a1f9e4.

You don't immediately realize without knowing this convention that the g isn't part of the sha and wonder why you can't find the commit. Is there a reason for the prefix or could there be an option to turn it off?

[AArnott]

It stands for git, and provides a more deterministic way to ascertain that what follows is the commit ID. I don't remember where it came from (I didn't invent the convention).

I've heard this feedback several times though, and I sympathize with the inconvenience of not being able to just double-click to select the "word" and paste it somewhere else without having to trim off the leading g.

I'm not sure anyone even likes the leading g (as folks don't tend to reinforce behavior that they like), so while an option to remove it seems perfectly reasonable, it's worth considering simply removing it entirely, or at least making the option default to removal.

I'm planning some breaking changes for a 3.0 version, and changing this behavior (or at least the default) would be well-placed for the 3.0 version, I think. And perhaps we can add the option in 2.3, but change its default in 3.0.

[AArnott]

Anyone reading this issue should please vote up or down on the original issue description. I'm interested in comparing the vote count.

[AArnott]

So... now I know why the g prefix is there. Without it, if the commit id happens to start with a number, nuget produces warnings:

This works great (when the commit starts with a letter):

Successfully created package '/root/bin/Debug/root.42.42.4-f92b4f1cbd.nupkg'.

But when the commit starts with a number:

Successfully created package '/root/bin/Debug/root.42.42.3-7d637a3dc6.nupkg'.
/usr/share/dotnet/sdk/2.1.403/Sdks/NuGet.Build.Tasks.Pack/build/NuGet.Build.Tasks.Pack.targets(199,5): warning NU5105: The package version '42.42.3-7d637a3dc6' uses SemVer 2.0.0 or components of SemVer 1.0.0 that are not supported on legacy clients. Change the package version to a SemVer 1.0.0 string. If the version contains a release label it must start with a letter. This message can be ignored if the package is not intended for older clients. [/root/root.csproj]

So, that stinks.

I could still make it an option, or make the g appear in only certain contexts and not others, but I'm worried it will be confusing/frustrating if the g appears in some places but not others since folks will have an even harder time predicting and understanding when/where it appears.

[AArnott]

I think the approach to fix this should be that we remove the g whenever the version.json file has opted into semver 2 for nuget packages. Or in other words, we use the g only for nuget package versions, and only when using semver 1 rules (which is the default).

[akoeplinger]

@AArnott how about we replace the g with git-? That should make it clearer that the following is a git commit sha, e.g. root.42.42.4-git-f92b4f1cbd.nupkg

This should still be compliant with SemVer1 rules.

[gitfool]

I would prefer a g prefix, when enabled, since it’s a “standard” convention after all. For semver 2, it would be nice to drop the prefix, but then I’m now used to seeing it everywhere, e.g. msbuild output, so I guess ultimately it should be configurable?