Merge pull request #132 from onovotny/semver-choice

Add option to choose SemVer option

Author: AArnott

doc/versionJson.md

@@ -25,6 +25,9 @@ The content of the version.json file is a JSON serialized object with these prop
   "assemblyVersion": "x.y", // optional. Use when x.y for AssemblyVersionAttribute differs from the default version property.
   "buildNumberOffset": "zOffset", // optional. Use when you need to add/subtract a fixed value from the computed build number.
   "semVer1NumericIdentifierPadding": 4, // optional. Use when your -prerelease includes numeric identifiers and need semver1 support.
+  "nugetPackageVersion": {
+     "semVer": 1 // optional. Set to either 1 or 2 to control how the NuGet package version string is generated. Default is 1.
+  },
   "publicReleaseRefSpec": [
     "^refs/heads/master$", // we release out of master
     "^refs/tags/v\\d+\\.\\d+" // we also release tags starting with vN.N

src/NerdBank.GitVersioning.Tests/BuildIntegrationTests.cs

@@ -72,6 +72,8 @@ public BuildIntegrationTests(ITestOutputHelper logger)
         }
     }
 
+    private string CommitIdShort => this.Repo.Head.Commits.First().Id.Sha.Substring(0, 10);
+
     protected override void Dispose(bool disposing)
     {
         Environment.SetEnvironmentVariable("_NBGV_UnitTest", string.Empty);
@@ -578,11 +580,15 @@ public async Task BuildNumber_SetInCI(VersionOptions versionOptions, IReadOnlyDi
 
     [Theory]
     [PairwiseData]
-    public async Task BuildNumber_VariousOptions(bool isPublic, VersionOptions.CloudBuildNumberCommitWhere where, VersionOptions.CloudBuildNumberCommitWhen when, [CombinatorialValues(0, 1, 2)] int extraBuildMetadataCount)
+    public async Task BuildNumber_VariousOptions(bool isPublic, VersionOptions.CloudBuildNumberCommitWhere where, VersionOptions.CloudBuildNumberCommitWhen when, [CombinatorialValues(0, 1, 2)] int extraBuildMetadataCount, [CombinatorialValues(1, 2)] int semVer)
     {
         var versionOptions = BuildNumberVersionOptionsBasis;
         versionOptions.CloudBuild.BuildNumber.IncludeCommitId.Where = where;
         versionOptions.CloudBuild.BuildNumber.IncludeCommitId.When = when;
+        versionOptions.NuGetPackageVersion = new VersionOptions.NuGetPackageVersionOptions
+        {
+            SemVer = semVer,
+        };
         this.WriteVersionFile(versionOptions);
         this.InitializeSourceControl();
 
@@ -828,7 +834,7 @@ private void AssertStandardProperties(VersionOptions versionOptions, BuildResult
     {
         int versionHeight = this.Repo.GetVersionHeight(relativeProjectDirectory);
         Version idAsVersion = this.Repo.GetIdAsVersion(relativeProjectDirectory);
-        string commitIdShort = this.Repo.Head.Commits.First().Id.Sha.Substring(0, 10);
+        string commitIdShort = this.CommitIdShort;
         Version version = this.Repo.GetIdAsVersion(relativeProjectDirectory);
         Version assemblyVersion = GetExpectedAssemblyVersion(versionOptions, version);
         var additionalBuildMetadata = from item in buildResult.BuildResult.ProjectStateAfterBuild.GetItems("BuildMetadata")
@@ -839,6 +845,8 @@ private void AssertStandardProperties(VersionOptions versionOptions, BuildResult
             expectedBuildMetadata += "." + string.Join(".", additionalBuildMetadata);
         }
 
+        string expectedBuildMetadataWithoutCommitId = additionalBuildMetadata.Any() ? $"+{string.Join(".", additionalBuildMetadata)}" : string.Empty;
+
         Assert.Equal($"{version}", buildResult.AssemblyFileVersion);
         Assert.Equal($"{idAsVersion.Major}.{idAsVersion.Minor}.{idAsVersion.Build}{versionOptions.Version.Prerelease}{expectedBuildMetadata}", buildResult.AssemblyInformationalVersion);
 
@@ -858,10 +866,15 @@ private void AssertStandardProperties(VersionOptions versionOptions, BuildResult
         Assert.Equal(versionOptions.Version.Prerelease, buildResult.PrereleaseVersion);
         Assert.Equal(expectedBuildMetadata, buildResult.SemVerBuildSuffix);
 
-        string pkgVersionSuffix = buildResult.PublicRelease
-            ? string.Empty
-            : $"-g{commitIdShort}";
-        Assert.Equal($"{idAsVersion.Major}.{idAsVersion.Minor}.{idAsVersion.Build}{GetSemVer1PrereleaseTag(versionOptions)}{pkgVersionSuffix}", buildResult.NuGetPackageVersion);
+        // NuGet is now SemVer 2.0 and will pass additional build metadata if provided
+        bool semVer2 = (versionOptions?.NuGetPackageVersion ?? VersionOptions.NuGetPackageVersionOptions.DefaultInstance).SemVer == 2;
+        string pkgVersionSuffix = buildResult.PublicRelease ? string.Empty : $"-g{commitIdShort}";
+        if (semVer2)
+        {
+            pkgVersionSuffix += expectedBuildMetadataWithoutCommitId;
+        }
+
+        Assert.Equal($"{idAsVersion.Major}.{idAsVersion.Minor}.{idAsVersion.Build}{GetSemVerAppropriatePrereleaseTag(versionOptions)}{pkgVersionSuffix}", buildResult.NuGetPackageVersion);
 
         var buildNumberOptions = versionOptions.CloudBuild?.BuildNumber ?? new VersionOptions.CloudBuildNumberOptions();
         if (buildNumberOptions.Enabled)
@@ -893,9 +906,11 @@ private void AssertStandardProperties(VersionOptions versionOptions, BuildResult
         }
     }
 
-    private static string GetSemVer1PrereleaseTag(VersionOptions versionOptions)
+    private static string GetSemVerAppropriatePrereleaseTag(VersionOptions versionOptions)
     {
-        return versionOptions.Version.Prerelease?.Replace('.', '-');
+        return (versionOptions.NuGetPackageVersion ?? VersionOptions.NuGetPackageVersionOptions.DefaultInstance).SemVer == 1
+            ? versionOptions.Version.Prerelease?.Replace('.', '-')
+            : versionOptions.Version.Prerelease;
     }
 
     private async Task<BuildResults> BuildAsync(string target = Targets.GetBuildVersion, LoggerVerbosity logVerbosity = LoggerVerbosity.Detailed, bool assertSuccessfulBuild = true)

src/NerdBank.GitVersioning.Tests/VersionOracleTests.cs

@@ -1,4 +1,5 @@
 using System.IO;
+using System.Linq;
 using LibGit2Sharp;
 using Nerdbank.GitVersioning;
 using Nerdbank.GitVersioning.Tests;
@@ -12,6 +13,8 @@ public VersionOracleTests(ITestOutputHelper logger)
     {
     }
 
+    private string CommitIdShort => this.Repo.Head.Commits.First().Id.Sha.Substring(0, 10);
+
     [Fact]
     public void Submodule_RecognizedWithCorrectVersion()
     {
@@ -149,4 +152,85 @@ public void SemVer1PrereleaseConversionPadding()
         oracle.PublicRelease = true;
         Assert.Equal("7.8.9-foo-025", oracle.SemVer1);
     }
+
+    [Fact]
+    public void DefaultNuGetPackageVersionIsSemVer1PublicRelease()
+    {
+        VersionOptions workingCopyVersion = new VersionOptions
+        {
+            Version = SemanticVersion.Parse("7.8.9-foo.25"),
+            SemVer1NumericIdentifierPadding = 2,
+        };
+        this.WriteVersionFile(workingCopyVersion);
+        this.InitializeSourceControl();
+        var oracle = VersionOracle.Create(this.RepoPath);
+        oracle.PublicRelease = true;
+        Assert.Equal($"7.8.9-foo-25", oracle.NuGetPackageVersion);
+    }
+
+    [Fact]
+    public void DefaultNuGetPackageVersionIsSemVer1NonPublicRelease()
+    {
+        VersionOptions workingCopyVersion = new VersionOptions
+        {
+            Version = SemanticVersion.Parse("7.8.9-foo.25"),
+            SemVer1NumericIdentifierPadding = 2,
+        };
+        this.WriteVersionFile(workingCopyVersion);
+        this.InitializeSourceControl();
+        var oracle = VersionOracle.Create(this.RepoPath);
+        oracle.PublicRelease = false;
+        Assert.Equal($"7.8.9-foo-25-g{this.CommitIdShort}", oracle.NuGetPackageVersion);
+    }
+
+    [Fact]
+    public void NpmPackageVersionIsSemVer1()
+    {
+        VersionOptions workingCopyVersion = new VersionOptions
+        {
+            Version = SemanticVersion.Parse("7.8.9-foo.25"),
+            SemVer1NumericIdentifierPadding = 2
+        };
+        this.WriteVersionFile(workingCopyVersion);
+        this.InitializeSourceControl();
+        var oracle = VersionOracle.Create(this.RepoPath);
+        oracle.PublicRelease = true;
+        Assert.Equal("7.8.9-foo-25", oracle.NpmPackageVersion);
+    }
+
+    [Fact]
+    public void CanSetSemVer2ForNuGetPackageVersionPublicRelease()
+    {
+        VersionOptions workingCopyVersion = new VersionOptions
+        {
+            Version = SemanticVersion.Parse("7.8.9-foo.25"),
+            NuGetPackageVersion = new VersionOptions.NuGetPackageVersionOptions
+            {
+                SemVer = 2,
+            }
+        };
+        this.WriteVersionFile(workingCopyVersion);
+        this.InitializeSourceControl();
+        var oracle = VersionOracle.Create(this.RepoPath);
+        oracle.PublicRelease = true;
+        Assert.Equal($"7.8.9-foo.25", oracle.NuGetPackageVersion);
+    }
+
+    [Fact]
+    public void CanSetSemVer2ForNuGetPackageVersionNonPublicRelease()
+    {
+        VersionOptions workingCopyVersion = new VersionOptions
+        {
+            Version = SemanticVersion.Parse("7.8.9-foo.25"),
+            NuGetPackageVersion = new VersionOptions.NuGetPackageVersionOptions
+            {
+                SemVer = 2,
+            }
+        };
+        this.WriteVersionFile(workingCopyVersion);
+        this.InitializeSourceControl();
+        var oracle = VersionOracle.Create(this.RepoPath);
+        oracle.PublicRelease = false;
+        Assert.Equal($"7.8.9-foo.25.g{this.CommitIdShort}", oracle.NuGetPackageVersion);
+    }
 }

src/NerdBank.GitVersioning/VersionOptions.cs

@@ -65,6 +65,12 @@ public class VersionOptions : IEquatable<VersionOptions>
         [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)]
         public int? SemVer1NumericIdentifierPadding { get; set; }
 
+        /// <summary>
+        /// Gets or sets the options around NuGet version strings
+        /// </summary>
+        [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)]
+        public NuGetPackageVersionOptions NuGetPackageVersion { get; set; }
+
         /// <summary>
         /// Gets or sets an array of regular expressions that describes branch or tag names that should
         /// be built with PublicRelease=true as the default value on build servers.
@@ -131,6 +137,7 @@ public bool Equals(VersionOptions other)
 
             return EqualityComparer<SemanticVersion>.Default.Equals(this.Version, other.Version)
                 && EqualityComparer<AssemblyVersionOptions>.Default.Equals(this.AssemblyVersion, other.AssemblyVersion)
+                && EqualityComparer<NuGetPackageVersionOptions>.Default.Equals(this.NuGetPackageVersion, other.NuGetPackageVersion)
                 && EqualityComparer<CloudBuildOptions>.Default.Equals(this.CloudBuild ?? CloudBuildOptions.DefaultInstance, other.CloudBuild ?? CloudBuildOptions.DefaultInstance)
                 && this.BuildNumberOffset == other.BuildNumberOffset;
         }
@@ -150,8 +157,61 @@ internal bool IsDefaultVersionTheOnlyPropertySet
 
         internal bool ShouldSerializeAssemblyVersion() => !(this.AssemblyVersion?.IsDefault ?? true);
 
+        internal bool ShouldSerializeNuGetPackageVersion() => !(this.NuGetPackageVersion?.IsDefault ?? true);
+
         internal bool ShouldSerializeCloudBuild() => !(this.CloudBuild?.IsDefault ?? true);
 
+        /// <summary>
+        /// The class that contains settings for the <see cref="NuGetPackageVersion" /> property.
+        /// </summary>
+        public class NuGetPackageVersionOptions : IEquatable<NuGetPackageVersionOptions>
+        {
+            /// <summary>
+            /// Default value for <see cref="SemVer"/>
+            /// </summary>
+            private const float DefaultNuGetPackageVersion = 1.0f;
+
+            /// <summary>
+            /// The default (uninitialized) instance.
+            /// </summary>
+            public static readonly NuGetPackageVersionOptions DefaultInstance = new NuGetPackageVersionOptions();
+
+            /// <summary>
+            /// Initializes a new instance of the <see cref="NuGetPackageVersionOptions" /> class.
+            /// </summary>
+            public NuGetPackageVersionOptions()
+            {
+            }
+
+            /// <summary>
+            /// Gets or sets the version of SemVer (e.g. 1 or 2) that should be used when generating the package version.
+            /// </summary>
+            [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)]
+            [DefaultValue(DefaultNuGetPackageVersion)]
+            public float SemVer { get; set; } = DefaultNuGetPackageVersion;
+
+            /// <inheritdoc />
+            public override bool Equals(object obj) => this.Equals(obj as NuGetPackageVersionOptions);
+
+            /// <inheritdoc />
+            public bool Equals(NuGetPackageVersionOptions other)
+            {
+                return other != null
+                       && this.SemVer == other.SemVer;
+            }
+
+            /// <inheritdoc />
+            public override int GetHashCode()
+            {
+                return this.SemVer.GetHashCode();
+            }
+
+            /// <summary>
+            /// Gets a value indicating whether this instance is equivalent to the default instance.
+            /// </summary>
+            internal bool IsDefault => this.Equals(DefaultInstance);
+        }
+
         /// <summary>
         /// Describes the details of how the AssemblyVersion value will be calculated.
         /// </summary>

src/NerdBank.GitVersioning/VersionOptionsContractResolver.cs

@@ -20,6 +20,11 @@ protected override JsonProperty CreateProperty(MemberInfo member, MemberSerializ
                 property.ShouldSerialize = instance => ((VersionOptions)instance).ShouldSerializeAssemblyVersion();
             }
 
+            if (property.DeclaringType == typeof(VersionOptions) && member.Name == nameof(VersionOptions.NuGetPackageVersion))
+            {
+                property.ShouldSerialize = instance => ((VersionOptions)instance).ShouldSerializeNuGetPackageVersion();
+            }
+
             if (property.DeclaringType == typeof(VersionOptions) && member.Name == nameof(VersionOptions.CloudBuild))
             {
                 property.ShouldSerialize = instance => ((VersionOptions)instance).ShouldSerializeCloudBuild();

src/NerdBank.GitVersioning/VersionOracle.cs

@@ -242,7 +242,7 @@ public IDictionary<string, string> CloudBuildVersionVars
         /// <summary>
         /// Gets the version to use for NuGet packages.
         /// </summary>
-        public string NuGetPackageVersion => this.SemVer1;
+        public string NuGetPackageVersion => (this.VersionOptions?.NuGetPackageVersion ?? VersionOptions.NuGetPackageVersionOptions.DefaultInstance).SemVer == 1 ? this.SemVer1 : this.SemVer2;
 
         /// <summary>
         /// Gets the version to use for NPM packages.
@@ -271,11 +271,21 @@ public IDictionary<string, string> CloudBuildVersionVars
         private string SemVer1BuildMetadata =>
             this.PublicRelease ? string.Empty : $"-g{this.GitCommitIdShort}";
 
+        /// <summary>
+        /// Gets the build metadata that is appropriate for SemVer2 use.
+        /// </summary>
+        /// <remarks>
+        /// We always put the commit ID in the -prerelease tag for non-public releases.
+        /// But for public releases, we don't include it in the +buildMetadata section since it may be confusing for NuGet.
+        /// See https://github.com/AArnott/Nerdbank.GitVersioning/pull/132#issuecomment-307208561
+        /// </remarks>
         private string SemVer2BuildMetadata =>
-            FormatBuildMetadata(this.PublicRelease ? this.BuildMetadata : this.BuildMetadataWithCommitId);
+            (this.PublicRelease ? string.Empty : this.GitCommitIdShortForNonPublicPrereleaseTag) + FormatBuildMetadata(this.BuildMetadata);
 
         private string PrereleaseVersionSemVer1 => MakePrereleaseSemVer1Compliant(this.PrereleaseVersion, SemVer1NumericIdentifierPadding);
 
+        private string GitCommitIdShortForNonPublicPrereleaseTag => (string.IsNullOrEmpty(this.PrereleaseVersion) ? "-" : ".") + $"g{this.GitCommitIdShort}";
+
         private VersionOptions.CloudBuildNumberOptions CloudBuildNumberOptions { get; }
 
         private int VersionHeightWithOffset => this.VersionHeight + this.VersionHeightOffset;

src/NerdBank.GitVersioning/version.schema.json

@@ -39,6 +39,19 @@
       "minimum": 1,
       "maximum": 6
     },
+    "nugetPackageVersion": {
+      "type": "object",
+      "description": "Details for how and what the generated version for NuGet packages will be.",
+      "properties": {
+        "semVer": {
+          "type": "integer",
+          "description": "The version of SemVer (e.g. 1 or 2) that should be used when generating the package version.",
+          "default": 1,
+          "minimum": 1,
+          "maximum": 2
+        }
+      }
+    },
     "publicReleaseRefSpec": {
       "type": "array",
       "description": "An array of regular expressions that may match a ref (branch or tag) that should be built with PublicRelease=true as the default value. The ref matched against is in its canonical form (e.g. refs/heads/master)",