Skip to content

Commit

Permalink
Update the docs on pre-release comparator handling
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
mattfarina committed Apr 9, 2018
1 parent 8d82589 commit ba6b639
Showing 1 changed file with 17 additions and 6 deletions.
23 changes: 17 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down

0 comments on commit ba6b639

Please sign in to comment.