Merge pull request #271 from tanishiking/update-scaladoc-semantic-version-selector

Update scaladoc for SemanticVersionSelector

core/src/main/contraband-scala/sbt/librarymanagement/SemanticSelector.scala

@@ -30,10 +30,6 @@ package sbt.librarymanagement
  * The (intersection) set of comparators can combined by ` || ` (spaces are required) to form the
  * union set of the intersection sets. So the semantic selector is in disjunctive normal form.
  * 
- * Metadata and pre-release of VersionNumber are ignored.
- * So `1.0.0` matches any versions that have `1.0.0` as normal version with any pre-release version
- * or any metadata like `1.0.0-alpha`, `1.0.0+metadata`.
- * 
  * Wildcard (`x`, `X`, `*`) can be used to match any number of minor or patch version.
  * Actually, `1.0.x` is equivalent to `=1.0` (that is equivalent to `>=1.0.0 <1.1.0`)
  * 
@@ -41,6 +37,26 @@ package sbt.librarymanagement
  * So `1.2.3 - 4.5.6` is equivalent to `>=1.2.3 <=4.5.6`.
  * Both sides of comparators around - are required and they can not have any operators.
  * For example, `>=1.2.3 - 4.5.6` is invalid.
+ * 
+ * The order of versions basically follows the rule specified in https://semver.org/#spec-item-11
+ * > When major, minor, and patch are equal, a pre-release version has lower precedence
+ * > than a normal version. Example: 1.0.0-alpha < 1.0.0.
+ * > Precedence for two pre-release versions with the same major, minor, and patch version
+ * > Must be determined by comparing each dot separated identifier from left to right
+ * > until a difference is found as follows:
+ * > identifiers consisting of only digits are compared numerically
+ * > and identifiers with letters or hyphens are compared lexically in ASCII sort order.
+ * > Numeric identifiers always have lower precedence than non-numeric identifiers.
+ * > A larger set of pre-release fields has a higher precedence than a smaller set,
+ * > if all of the preceding identifiers are equal.
+ * > Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.
+ * 
+ * The differences from the original specification are following
+ * - `SemanticVersionSelector` separetes the pre-release fields by hyphen instead of dot
+ * - hyphen cannot be used in pre-release identifiers because it is used as separator for pre-release fields
+ * 
+ * Therefore, in order to match pre-release versions like `1.0.0-beta`
+ * we need to explicitly specify the pre-release identifiers like `>=1.0.0-alpha`.
  */
 final class SemanticSelector private (
   val selectors: Seq[sbt.internal.librarymanagement.SemSelAndChunk]) extends Serializable {

core/src/main/contraband/librarymanagement2.json

@@ -49,17 +49,33 @@
         "The (intersection) set of comparators can combined by ` || ` (spaces are required) to form the",
         "union set of the intersection sets. So the semantic selector is in disjunctive normal form.",
         "",
-        "Metadata and pre-release of VersionNumber are ignored.",
-        "So `1.0.0` matches any versions that have `1.0.0` as normal version with any pre-release version",
-        "or any metadata like `1.0.0-alpha`, `1.0.0+metadata`.",
-        "",
         "Wildcard (`x`, `X`, `*`) can be used to match any number of minor or patch version.",
         "Actually, `1.0.x` is equivalent to `=1.0` (that is equivalent to `>=1.0.0 <1.1.0`)",
         "",
         "The hyphen range like `1.2.3 - 4.5.6` matches inclusive set of versions.",
         "So `1.2.3 - 4.5.6` is equivalent to `>=1.2.3 <=4.5.6`.",
         "Both sides of comparators around - are required and they can not have any operators.",
-        "For example, `>=1.2.3 - 4.5.6` is invalid."
+        "For example, `>=1.2.3 - 4.5.6` is invalid.",
+        "",
+        "The order of versions basically follows the rule specified in https://semver.org/#spec-item-11",
+        "> When major, minor, and patch are equal, a pre-release version has lower precedence",
+        "> than a normal version. Example: 1.0.0-alpha < 1.0.0.",
+        "> Precedence for two pre-release versions with the same major, minor, and patch version",
+        "> Must be determined by comparing each dot separated identifier from left to right",
+        "> until a difference is found as follows:",
+        "> identifiers consisting of only digits are compared numerically",
+        "> and identifiers with letters or hyphens are compared lexically in ASCII sort order.",
+        "> Numeric identifiers always have lower precedence than non-numeric identifiers.",
+        "> A larger set of pre-release fields has a higher precedence than a smaller set,",
+        "> if all of the preceding identifiers are equal.",
+        "> Example: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-alpha.beta < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0.",
+        "",
+        "The differences from the original specification are following",
+        "- `SemanticVersionSelector` separetes the pre-release fields by hyphen instead of dot",
+        "- hyphen cannot be used in pre-release identifiers because it is used as separator for pre-release fields",
+        "",
+        "Therefore, in order to match pre-release versions like `1.0.0-beta`",
+        "we need to explicitly specify the pre-release identifiers like `>=1.0.0-alpha`."
       ],
       "generateCodec": false,
       "fields": [