Improve semver1 conversion from semver2

Author: AArnott

doc/versionJson.md

@@ -24,9 +24,10 @@ The content of the version.json file is a JSON serialized object with these prop
   "version": "x.y-prerelease", // required
   "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.
   "publicReleaseRefSpec": [
     "^refs/heads/master$", // we release out of master
-    "^refs/tags/v\\d\\.\\d" // we also release tags starting with vN.N
+    "^refs/tags/v\\d+\\.\\d+" // we also release tags starting with vN.N
   ],
   "cloudBuild": {
     "setVersionVariables": true,
@@ -43,6 +44,11 @@ The content of the version.json file is a JSON serialized object with these prop
 
 The `x` and `y` variables are for your use to specify a version that is meaningful
 to your customers. Consider using [semantic versioning][semver] for guidance.
+You may optionally supply a third integer in the version (i.e. x.y.z),
+in which case the git version height is specified as the fourth integer,
+which only appears in certain version representations.
+Alternatively, you can include the git version height in the -prerelease tag using
+syntax such as: `1.2.3-beta.{height}`
 
 The optional -prerelease tag allows you to indicate that you are building prerelease software.
 

src/NerdBank.GitVersioning.Tests/BuildIntegrationTests.cs

@@ -104,6 +104,7 @@ public async Task GetBuildVersion_WithThreeVersionIntegers()
         VersionOptions workingCopyVersion = new VersionOptions
         {
             Version = SemanticVersion.Parse("7.8.9-beta.3"),
+            SemVer1NumericIdentifierPadding = 1,
         };
         this.WriteVersionFile(workingCopyVersion);
         this.InitializeSourceControl();
@@ -860,7 +861,7 @@ private void AssertStandardProperties(VersionOptions versionOptions, BuildResult
         string pkgVersionSuffix = buildResult.PublicRelease
             ? string.Empty
             : $"-g{commitIdShort}";
-        Assert.Equal($"{idAsVersion.Major}.{idAsVersion.Minor}.{idAsVersion.Build}{versionOptions.Version.Prerelease}{pkgVersionSuffix}", buildResult.NuGetPackageVersion);
+        Assert.Equal($"{idAsVersion.Major}.{idAsVersion.Minor}.{idAsVersion.Build}{GetSemVer1PrereleaseTag(versionOptions)}{pkgVersionSuffix}", buildResult.NuGetPackageVersion);
 
         var buildNumberOptions = versionOptions.CloudBuild?.BuildNumber ?? new VersionOptions.CloudBuildNumberOptions();
         if (buildNumberOptions.Enabled)
@@ -892,6 +893,11 @@ private void AssertStandardProperties(VersionOptions versionOptions, BuildResult
         }
     }
 
+    private static string GetSemVer1PrereleaseTag(VersionOptions versionOptions)
+    {
+        return versionOptions.Version.Prerelease?.Replace('.', '-');
+    }
+
     private async Task<BuildResults> BuildAsync(string target = Targets.GetBuildVersion, LoggerVerbosity logVerbosity = LoggerVerbosity.Detailed, bool assertSuccessfulBuild = true)
     {
         var eventLogger = new MSBuildLogger { Verbosity = LoggerVerbosity.Minimal };

src/NerdBank.GitVersioning.Tests/VersionOracleTests.cs

@@ -112,4 +112,41 @@ public void HeightInBuildMetadata()
         Assert.Equal(1, oracle.VersionHeight);
         Assert.Equal(2, oracle.VersionHeightOffset);
     }
+
+    [Theory]
+    [InlineData("7.8.9-foo.25", "7.8.9-foo-0025")]
+    [InlineData("7.8.9-foo.25s", "7.8.9-foo-25s")]
+    [InlineData("7.8.9-foo.s25", "7.8.9-foo-s25")]
+    [InlineData("7.8.9-foo.25.bar-24.13-11", "7.8.9-foo-0025-bar-24-13-11")]
+    [InlineData("7.8.9-25.bar.baz-25", "7.8.9-0025-bar-baz-25")]
+    [InlineData("7.8.9-foo.5.bar.1.43.baz", "7.8.9-foo-0005-bar-0001-0043-baz")]
+    public void SemVer1PrereleaseConversion(string semVer2, string semVer1)
+    {
+        VersionOptions workingCopyVersion = new VersionOptions
+        {
+            Version = SemanticVersion.Parse(semVer2),
+            BuildNumberOffset = 2,
+        };
+        this.WriteVersionFile(workingCopyVersion);
+        this.InitializeSourceControl();
+        var oracle = VersionOracle.Create(this.RepoPath);
+        oracle.PublicRelease = true;
+        Assert.Equal(semVer1, oracle.SemVer1);
+    }
+
+    [Fact]
+    public void SemVer1PrereleaseConversionPadding()
+    {
+        VersionOptions workingCopyVersion = new VersionOptions
+        {
+            Version = SemanticVersion.Parse("7.8.9-foo.25"),
+            BuildNumberOffset = 2,
+            SemVer1NumericIdentifierPadding = 3,
+        };
+        this.WriteVersionFile(workingCopyVersion);
+        this.InitializeSourceControl();
+        var oracle = VersionOracle.Create(this.RepoPath);
+        oracle.PublicRelease = true;
+        Assert.Equal("7.8.9-foo-025", oracle.SemVer1);
+    }
 }

src/NerdBank.GitVersioning/VersionOptions.cs

@@ -59,6 +59,12 @@ public class VersionOptions : IEquatable<VersionOptions>
         [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)]
         public int BuildNumberOffset { get; set; }
 
+        /// <summary>
+        /// Gets or sets the minimum number of digits to use for numeric identifiers in SemVer 1.
+        /// </summary>
+        [JsonProperty(DefaultValueHandling = DefaultValueHandling.Ignore)]
+        public int? SemVer1NumericIdentifierPadding { 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.

src/NerdBank.GitVersioning/VersionOracle.cs

@@ -15,6 +15,11 @@
     /// </summary>
     public class VersionOracle
     {
+        /// <summary>
+        /// A regex that matches on numeric identifiers for prerelease or build metadata.
+        /// </summary>
+        private static readonly Regex NumericIdentifierRegex = new Regex(@"(?<![\w-])(\d+)(?![\w-])");
+
         /// <summary>
         /// The cloud build suppport, if any.
         /// </summary>
@@ -249,7 +254,7 @@ public IDictionary<string, string> CloudBuildVersionVars
         /// when <see cref="PublicRelease"/> is <c>false</c>.
         /// </summary>
         public string SemVer1 =>
-            $"{this.Version.ToStringSafe(3)}{this.PrereleaseVersion}{this.SemVer1BuildMetadata}";
+            $"{this.Version.ToStringSafe(3)}{this.PrereleaseVersionSemVer1}{this.SemVer1BuildMetadata}";
 
         /// <summary>
         /// Gets a SemVer 2.0 compliant string that represents this version, including a +gCOMMITID suffix
@@ -258,12 +263,19 @@ public IDictionary<string, string> CloudBuildVersionVars
         public string SemVer2 =>
             $"{this.Version.ToStringSafe(3)}{this.PrereleaseVersion}{this.SemVer2BuildMetadata}";
 
+        /// <summary>
+        /// Gets the minimum number of digits to use for numeric identifiers in SemVer 1.
+        /// </summary>
+        public int SemVer1NumericIdentifierPadding => this.VersionOptions?.SemVer1NumericIdentifierPadding ?? 4;
+
         private string SemVer1BuildMetadata =>
             this.PublicRelease ? string.Empty : $"-g{this.GitCommitIdShort}";
 
         private string SemVer2BuildMetadata =>
             FormatBuildMetadata(this.PublicRelease ? this.BuildMetadata : this.BuildMetadataWithCommitId);
 
+        private string PrereleaseVersionSemVer1 => MakePrereleaseSemVer1Compliant(this.PrereleaseVersion, SemVer1NumericIdentifierPadding);
+
         private VersionOptions.CloudBuildNumberOptions CloudBuildNumberOptions { get; }
 
         private int VersionHeightWithOffset => this.VersionHeight + this.VersionHeightOffset;
@@ -343,5 +355,31 @@ private static Version GetAssemblyVersion(Version version, VersionOptions versio
         /// <param name="prereleaseOrBuildMetadata">The prerelease or build metadata.</param>
         /// <returns>The specified string, with macros substituted for actual values.</returns>
         private string ReplaceMacros(string prereleaseOrBuildMetadata) => prereleaseOrBuildMetadata?.Replace("{height}", this.VersionHeightWithOffset.ToString(CultureInfo.InvariantCulture));
+
+        /// <summary>
+        /// Converts a semver 2 compliant "-beta.5" prerelease tag to a semver 1 compatible one.
+        /// </summary>
+        /// <param name="prerelease">The semver 2 prerelease tag, including its leading hyphen.</param>
+        /// <param name="paddingSize">The minimum number of digits to use for any numeric identifier.</param>
+        /// <returns>A semver 1 compliant prerelease tag. For example "-beta-0005".</returns>
+        private static string MakePrereleaseSemVer1Compliant(string prerelease, int paddingSize)
+        {
+            if (string.IsNullOrEmpty(prerelease))
+            {
+                return prerelease;
+            }
+
+            string paddingFormatter = "{0:" + new string('0', paddingSize) + "}";
+
+            string semver1 = prerelease;
+
+            // Identify numeric identifiers and pad them.
+            Assumes.True(prerelease.StartsWith("-"));
+            semver1 = "-" + NumericIdentifierRegex.Replace(semver1.Substring(1), m => string.Format(CultureInfo.InvariantCulture, paddingFormatter, int.Parse(m.Groups[1].Value)));
+
+            semver1 = semver1.Replace('.', '-');
+
+            return semver1;
+        }
     }
 }

src/NerdBank.GitVersioning/version.schema.json

@@ -32,6 +32,13 @@
       "description": "A number to add to the git height when calculating the build number.",
       "default": 0
     },
+    "semVer1NumericIdentifierPadding": {
+      "type": "integer",
+      "description": "The minimum number of digits to use for numeric identifiers in SemVer 1.",
+      "default": 4,
+      "minimum": 1,
+      "maximum": 6
+    },
     "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)",