Merge branch 'develop' into stable

1 files changed, 27 insertions, 12 deletions

diff --git a/src/StardewModdingAPI.Toolkit/SemanticVersion.cs b/src/StardewModdingAPI.Toolkit/SemanticVersion.cs
index 156d58ce..a7990d13 100644
--- a/src/StardewModdingAPI.Toolkit/SemanticVersion.cs
+++ b/src/StardewModdingAPI.Toolkit/SemanticVersion.cs
@@ -4,7 +4,13 @@ using System.Text.RegularExpressions;
 namespace StardewModdingAPI.Toolkit
 {
     /// <summary>A semantic version with an optional release tag.</summary>
-    /// <remarks>The implementation is defined by Semantic Version 2.0 (http://semver.org/).</remarks>
+    /// <remarks>
+    /// The implementation is defined by Semantic Version 2.0 (https://semver.org/), with a few deviations:
+    /// - short-form "x.y" versions are supported (equivalent to "x.y.0");
+    /// - hyphens are synonymous with dots in prerelease tags (like "-unofficial.3-pathoschild");
+    /// - +build suffixes are not supported;
+    /// - and "-unofficial" in prerelease tags is always lower-precedence (e.g. "1.0-beta" is newer than "1.0-unofficial").
+    /// </remarks>
     public class SemanticVersion : ISemanticVersion
     {
         /*********
@@ -17,13 +23,7 @@ namespace StardewModdingAPI.Toolkit
         internal const string UnboundedVersionPattern = @"(?>(?<major>0|[1-9]\d*))\.(?>(?<minor>0|[1-9]\d*))(?>(?:\.(?<patch>0|[1-9]\d*))?)(?:-(?<prerelease>" + SemanticVersion.TagPattern + "))?";
 
         /// <summary>A regular expression matching a semantic version string.</summary>
-        /// <remarks>
-        /// This pattern is derived from the BNF documentation in the <a href="https://github.com/mojombo/semver">semver repo</a>,
-        /// with three important deviations intended to support Stardew Valley mod conventions:
-        /// - allows short-form "x.y" versions;
-        /// - allows hyphens in prerelease tags as synonyms for dots (like "-unofficial-update.3");
-        /// - doesn't allow '+build' suffixes.
-        /// </remarks>
+        /// <remarks>This pattern is derived from the BNF documentation in the <a href="https://github.com/mojombo/semver">semver repo</a>, with deviations to support the Stardew Valley mod conventions (see remarks on <see cref="SemanticVersion"/>).</remarks>
         internal static readonly Regex Regex = new Regex($@"^{SemanticVersion.UnboundedVersionPattern}$", RegexOptions.CultureInvariant | RegexOptions.IgnoreCase | RegexOptions.Compiled | RegexOptions.ExplicitCapture);
 
 
@@ -40,7 +40,14 @@ namespace StardewModdingAPI.Toolkit
         public int PatchVersion { get; }
 
         /// <summary>An optional prerelease tag.</summary>
-        public string Build { get; }
+        [Obsolete("Use " + nameof(ISemanticVersion.PrereleaseTag) + " instead")]
+        public string Build => this.PrereleaseTag;
+
+        /// <summary>An optional prerelease tag.</summary>
+        public string PrereleaseTag { get; }
+
+        /// <summary>Whether the version was parsed from the legacy object format.</summary>
+        public bool IsLegacyFormat { get; }
 
 
         /*********
@@ -51,12 +58,14 @@ namespace StardewModdingAPI.Toolkit
         /// <param name="minor">The minor version incremented for backwards-compatible changes.</param>
         /// <param name="patch">The patch version for backwards-compatible fixes.</param>
         /// <param name="tag">An optional prerelease tag.</param>
-        public SemanticVersion(int major, int minor, int patch, string tag = null)
+        /// <param name="isLegacyFormat">Whether the version was parsed from the legacy object format.</param>
+        public SemanticVersion(int major, int minor, int patch, string tag = null, bool isLegacyFormat = false)
         {
             this.MajorVersion = major;
             this.MinorVersion = minor;
             this.PatchVersion = patch;
-            this.Build = this.GetNormalisedTag(tag);
+            this.PrereleaseTag = this.GetNormalisedTag(tag);
+            this.IsLegacyFormat = isLegacyFormat;
 
             this.AssertValid();
         }
@@ -93,7 +102,7 @@ namespace StardewModdingAPI.Toolkit
             this.MajorVersion = int.Parse(match.Groups["major"].Value);
             this.MinorVersion = match.Groups["minor"].Success ? int.Parse(match.Groups["minor"].Value) : 0;
             this.PatchVersion = match.Groups["patch"].Success ? int.Parse(match.Groups["patch"].Value) : 0;
-            this.Build = match.Groups["prerelease"].Success ? this.GetNormalisedTag(match.Groups["prerelease"].Value) : null;
+            this.PrereleaseTag = match.Groups["prerelease"].Success ? this.GetNormalisedTag(match.Groups["prerelease"].Value) : null;
 
             this.AssertValid();
         }
@@ -255,6 +264,12 @@ namespace StardewModdingAPI.Toolkit
                 // compare if different
                 if (curParts[i] != otherParts[i])
                 {
+                    // unofficial is always lower-precedence
+                    if (otherParts[i].Equals("unofficial", StringComparison.InvariantCultureIgnoreCase))
+                        return curNewer;
+                    if (curParts[i].Equals("unofficial", StringComparison.InvariantCultureIgnoreCase))
+                        return curOlder;
+
                     // compare numerically if possible
                     {
                         if (int.TryParse(curParts[i], out int curNum) && int.TryParse(otherParts[i], out int otherNum))