luke
/
sbt
mirror of https://github.com/sbt/sbt.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update scaladoc for SemanticVersionSelector 

Fix for https://github.com/sbt/sbt/issues/4422
This commit is contained in:
tanishiking 2018-10-17 00:30:13 +09:00
parent 87393a3f9f
commit 1d429e4c51
2 changed files with 41 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
core/src/main/contraband-scala/sbt/librarymanagement/SemanticSelector.scala
View File

@ -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 {

26
core/src/main/contraband/librarymanagement2.json
View File

@ -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": [