From ba6b639e4977b97803d1fcafcf49fe6e4d993122 Mon Sep 17 00:00:00 2001 From: Matt Farina Date: Mon, 9 Apr 2018 17:01:11 -0400 Subject: [PATCH 1/2] Update the docs on pre-release comparator handling There has been confusion on the use of pre-releases in comparison ranges. This attempts to add more detail to help end users figure them out. --- README.md | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 3e934ed..78d278f 100644 --- a/README.md +++ b/README.md @@ -80,14 +80,25 @@ The basic comparisons are: * `>=`: greater than or equal to * `<=`: less than or equal to -_Note, according to the Semantic Version specification pre-releases may not be -API compliant with their release counterpart. It says,_ +## Working With Pre-release Versions -> _A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version._ +According to the Semantic Version specification pre-releases may not be +API compliant with their release counterpart. It says, -_SemVer comparisons without a pre-release value will skip pre-release versions. -For example, `>1.2.3` will skip pre-releases when looking at a list of values -while `>1.2.3-alpha.1` will evaluate pre-releases._ +> A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. + +SemVer comparisons without a pre-release value will skip pre-release versions. +For example, `>=1.2.3` will skip pre-releases when looking at a list of values +while `>=1.2.3-0` will evaluate and find pre-releases. + +The reason for the `0` as a pre-release version in the example comparison is +because pre-releases can only contain ASCII alphanumerics and hyphens (along with +`.` separators), per the spec. Sorting happens in ASCII sort order, again per the spec. The lowest character is a `0` in ASCII sort order (see an [ASCII Table](http://www.asciitable.com/)) + +Understanding ASCII sort ordering is important because A-Z comes before a-z. That +means `>=1.2.3-BETA` will return `1.2.3-alpha`. What you might expect from case +sensitivity doesn't apply here. This is due to ASCII sort ordering which is what +the spec specifies. ## Hyphen Range Comparisons From 0c3415da09dfa43a604d0945fc94c449e49438b5 Mon Sep 17 00:00:00 2001 From: Matt Farina Date: Tue, 10 Apr 2018 16:23:17 -0400 Subject: [PATCH 2/2] Adding more details on pre-releases --- README.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 78d278f..eb14755 100644 --- a/README.md +++ b/README.md @@ -82,13 +82,20 @@ The basic comparisons are: ## Working With Pre-release Versions +Pre-releases, for those not familiar with them, are used for software releases +prior to stable or generally available releases. Examples of pre-releases include +development, alpha, beta, and release candidate releases. A pre-release may be +a version such as `1.2.3-beta.1` while the stable release would be `1.2.3`. In the +order of precidence, pre-releases come before their associated releases. In this +example `1.2.3-beta.1 < 1.2.3`. + According to the Semantic Version specification pre-releases may not be API compliant with their release counterpart. It says, > A pre-release version indicates that the version is unstable and might not satisfy the intended compatibility requirements as denoted by its associated normal version. -SemVer comparisons without a pre-release value will skip pre-release versions. -For example, `>=1.2.3` will skip pre-releases when looking at a list of values +SemVer comparisons without a pre-release comparator will skip pre-release versions. +For example, `>=1.2.3` will skip pre-releases when looking at a list of releases while `>=1.2.3-0` will evaluate and find pre-releases. The reason for the `0` as a pre-release version in the example comparison is