semver 3.0.1 → 4.1.0

package/Makefile

@@ -8,12 +8,12 @@ all: $(files)
 clean:
 	rm -f $(files)
 
-semver.browser.js: head.js semver.js foot.js
-	( cat head.js; \
+semver.browser.js: head.js.txt semver.js foot.js.txt
+	( cat head.js.txt; \
 		cat semver.js | \
 			egrep -v '^ *\/\* nomin \*\/' | \
 			perl -pi -e 's/debug\([^\)]+\)//g'; \
-		cat foot.js ) > semver.browser.js
+		cat foot.js.txt ) > semver.browser.js
 
 semver.min.js: semver.browser.js
 	uglifyjs -m <semver.browser.js >semver.min.js

package/README.md

@@ -41,53 +41,170 @@ A leading `"="` or `"v"` character is stripped off and ignored.
 
 ## Ranges
 
-The following range styles are supported:
-
-* `1.2.3` A specific version.  When nothing else will do.  Must be a full
-  version number, with major, minor, and patch versions specified.
-  Note that build metadata is still ignored, so `1.2.3+build2012` will
-  satisfy this range.
-* `>1.2.3` Greater than a specific version.
-* `<1.2.3` Less than a specific version.  If there is no prerelease
-  tag on the version range, then no prerelease version will be allowed
-  either, even though these are technically "less than".
-* `>=1.2.3` Greater than or equal to.  Note that prerelease versions
-  are NOT equal to their "normal" equivalents, so `1.2.3-beta` will
-  not satisfy this range, but `2.3.0-beta` will.
-* `<=1.2.3` Less than or equal to.  In this case, prerelease versions
-  ARE allowed, so `1.2.3-beta` would satisfy.
+A `version range` is a set of `comparators` which specify versions
+that satisfy the range.
+
+A `comparator` is composed of an `operator` and a `version`.  The set
+of primitive `operators` is:
+
+* `<` Less than
+* `<=` Less than or equal to
+* `>` Greater than
+* `>=` Greater than or equal to
+* `=` Equal.  If no operator is specified, then equality is assumed,
+  so this operator is optional, but MAY be included.
+
+For example, the comparator `>=1.2.7` would match the versions
+`1.2.7`, `1.2.8`, `2.5.3`, and `1.3.9`, but not the versions `1.2.6`
+or `1.1.0`.
+
+Comparators can be joined by whitespace to form a `comparator set`,
+which is satisfied by the **intersection** of all of the comparators
+it includes.
+
+A range is composed of one or more comparator sets, joined by `||`.  A
+version matches a range if and only if every comparator in at least
+one of the `||`-separated comparator sets is satisfied by the version.
+
+For example, the range `>=1.2.7 <1.3.0` would match the versions
+`1.2.7`, `1.2.8`, and `1.2.99`, but not the versions `1.2.6`, `1.3.0`,
+or `1.1.0`.
+
+The range `1.2.7 || >=1.2.9 <2.0.0` would match the versions `1.2.7`,
+`1.2.9`, and `1.4.6`, but not the versions `1.2.8` or `2.0.0`.
+
+### Prerelease Tags
+
+If a version has a prerelease tag (for example, `1.2.3-alpha.3`) then
+it will only be allowed to satisfy comparator sets if at least one
+comparator with the same `[major, minor, patch]` tuple also has a
+prerelease tag.
+
+For example, the range `>1.2.3-alpha.3` would be allowed to match the
+version `1.2.3-alpha.7`, but it would *not* be satisfied by
+`3.4.5-alpha.9`, even though `3.4.5-alpha.9` is technically "greater
+than" `1.2.3-alpha.3` according to the SemVer sort rules.  The version
+range only accepts prerelease tags on the `1.2.3` version.  The
+version `3.4.5` *would* satisfy the range, because it does not have a
+prerelease flag, and `3.4.5` is greater than `1.2.3-alpha.7`.
+
+The purpose for this behavior is twofold.  First, prerelease versions
+frequently are updated very quickly, and contain many breaking changes
+that are (by the author's design) not yet fit for public consumption.
+Therefore, by default, they are excluded from range matching
+semantics.
+
+Second, a user who has opted into using a prerelease version has
+clearly indicated the intent to use *that specific* set of
+alpha/beta/rc versions.  By including a prerelease tag in the range,
+the user is indicating that they are aware of the risk.  However, it
+is still not appropriate to assume that they have opted into taking a
+similar risk on the *next* set of prerelease versions.
+
+### Advanced Range Syntax
+
+Advanced range syntax desugars to primitive comparators in
+deterministic ways.
+
+Advanced ranges may be combined in the same way as primitive
+comparators using white space or `||`.
+
+#### Hyphen Ranges `X.Y.Z - A.B.C`
+
+Specifies an inclusive set.
+
 * `1.2.3 - 2.3.4` := `>=1.2.3 <=2.3.4`
-* `~1.2.3` := `>=1.2.3-0 <1.3.0-0`  "Reasonably close to `1.2.3`".  When
-  using tilde operators, prerelease versions are supported as well,
-  but a prerelease of the next significant digit will NOT be
-  satisfactory, so `1.3.0-beta` will not satisfy `~1.2.3`.
-* `^1.2.3` := `>=1.2.3-0 <2.0.0-0`  "Compatible with `1.2.3`".  When
-  using caret operators, anything from the specified version (including
-  prerelease) will be supported up to, but not including, the next
-  major version (or its prereleases). `1.5.1` will satisfy `^1.2.3`,
-  while `1.2.2` and `2.0.0-beta` will not.
-* `^0.1.3` := `0.1.3` "Compatible with `0.1.3`". `0.x.x` versions are
-  special: since the semver spec specifies that `0.x.x` versions make
-  no stability guarantees, only the version specified is considered
-  valid.
-* `^0.0.2` := `0.0.2` "Only the version `0.0.2` is considered compatible"
-* `~1.2` := `>=1.2.0-0 <1.3.0-0` "Any version starting with `1.2`"
-* `^1.2` := `>=1.2.0-0 <2.0.0-0` "Any version compatible with `1.2`"
-* `1.2.x` := `>=1.2.0-0 <1.3.0-0` "Any version starting with `1.2`"
-* `1.2.*` Same as `1.2.x`.
-* `1.2` Same as `1.2.x`.
-* `~1` := `>=1.0.0-0 <2.0.0-0` "Any version starting with `1`"
-* `^1` := `>=1.0.0-0 <2.0.0-0` "Any version compatible with `1`"
-* `1.x` := `>=1.0.0-0 <2.0.0-0` "Any version starting with `1`"
-* `1.*` Same as `1.x`.
-* `1` Same as `1.x`.
-* `*` Any version whatsoever.
-* `x` Same as `*`.
-* `""` (just an empty string) Same as `*`.
-
-
-Ranges can be joined with either a space (which implies "and") or a
-`||` (which implies "or").
+
+If a partial version is provided as the first version in the inclusive
+range, then the missing pieces are replaced with zeroes.
+
+* `1.2 - 2.3.4` := `>=1.2.0 <=2.3.4`
+
+If a partial version is provided as the second version in the
+inclusive range, then all versions that start with the supplied parts
+of the tuple are accepted, but nothing that would be greater than the
+provided tuple parts.
+
+* `1.2.3 - 2.3` := `>=1.2.3 <2.4.0`
+* `1.2.3 - 2` := `>=1.2.3 <3.0.0`
+
+#### X-Ranges `1.2.x` `1.X` `1.2.*` `*`
+
+Any of `X`, `x`, or `*` may be used to "stand in" for one of the
+numeric values in the `[major, minor, patch]` tuple.
+
+* `*` := `>=0.0.0` (Any version satisfies)
+* `1.x` := `>=1.0.0 <2.0.0` (Matching major version)
+* `1.2.x` := `>=1.2.0 <1.3.0` (Matching major and minor versions)
+
+A partial version range is treated as an X-Range, so the special
+character is in fact optional.
+
+* `""` (empty string) := `*` := `>=0.0.0`
+* `1` := `1.x.x` := `>=1.0.0 <2.0.0`
+* `1.2` := `1.2.x` := `>=1.2.0 <1.3.0`
+
+#### Tilde Ranges `~1.2.3` `~1.2` `~1`
+
+Allows patch-level changes if a minor version is specified on the
+comparator.  Allows minor-level changes if not.
+
+* `~1.2.3` := `>=1.2.3 <1.(2+1).0` := `>=1.2.3 <1.3.0`
+* `~1.2` := `>=1.2.0 <1.(2+1).0` := `>=1.2.0 <1.3.0` (Same as `1.2.x`)
+* `~1` := `>=1.0.0 <(1+1).0.0` := `>=1.0.0 <2.0.0` (Same as `1.x`)
+* `~0.2.3` := `>=0.2.3 <0.(2+1).0` := `>=0.2.3 <0.3.0`
+* `~0.2` := `>=0.2.0 <0.(2+1).0` := `>=0.2.0 <0.3.0` (Same as `0.2.x`)
+* `~0` := `>=0.0.0 <(0+1).0.0` := `>=0.0.0 <1.0.0` (Same as `0.x`)
+* `~1.2.3-beta.2` := `>=1.2.3-beta.2 <1.3.0` Note that prereleases in
+  the `1.2.3` version will be allowed, if they are greater than or
+  equal to `beta.2`.  So, `1.2.3-beta.4` would be allowed, but
+  `1.2.4-beta.2` would not, because it is a prerelease of a
+  different `[major, minor, patch]` tuple.
+
+Note: this is the same as the `~>` operator in rubygems.
+
+#### Caret Ranges `^1.2.3` `^0.2.5` `^0.0.4`
+
+Allows changes that do not modify the left-most non-zero digit in the
+`[major, minor, patch]` tuple.  In other words, this allows patch and
+minor updates for versions `1.0.0` and above, patch updates for
+versions `0.X >=0.1.0`, and *no* updates for versions `0.0.X`.
+
+Many authors treat a `0.x` version as if the `x` were the major
+"breaking-change" indicator.
+
+Caret ranges are ideal when an author may make breaking changes
+between `0.2.4` and `0.3.0` releases, which is a common practice.
+However, it presumes that there will *not* be breaking changes between
+`0.2.4` and `0.2.5`.  It allows for changes that are presumed to be
+additive (but non-breaking), according to commonly observed practices.
+
+* `^1.2.3` := `>=1.2.3 <2.0.0`
+* `^0.2.3` := `>=0.2.3 <0.3.0`
+* `^0.0.3` := `>=0.0.3 <0.0.4`
+* `^1.2.3-beta.2` := `>=1.2.3-beta.2 <2.0.0` Note that prereleases in
+  the `1.2.3` version will be allowed, if they are greater than or
+  equal to `beta.2`.  So, `1.2.3-beta.4` would be allowed, but
+  `1.2.4-beta.2` would not, because it is a prerelease of a
+  different `[major, minor, patch]` tuple.
+* `^0.0.3-beta` := `>=0.0.3-beta <0.0.4`  Note that prereleases in the
+  `0.0.3` version *only* will be allowed, if they are greater than or
+  equal to `beta`.  So, `0.0.3-pr.2` would be allowed.
+
+When parsing caret ranges, a missing `patch` value desugars to the
+number `0`, but will allow flexibility within that value, even if the
+major and minor versions are both `0`.
+
+* `^1.2.x` := `>=1.2.0 <2.0.0`
+* `^0.0.x` := `>=0.0.0 <0.1.0`
+* `^0.0` := `>=0.0.0 <0.1.0`
+
+A missing `minor` and `patch` values will desugar to zero, but also
+allow flexibility within those values, even if the major version is
+zero.
+
+* `^1.x` := `>=1.0.0 <2.0.0`
+* `^0.x` := `>=0.0.0 <1.0.0`
 
 ## Functions
 

package/bin/semver

@@ -12,6 +12,7 @@ var argv = process.argv.slice(2)
   , inc = null
   , version = require("../package.json").version
   , loose = false
+  , identifier = undefined
   , semver = require("../semver")
   , reverse = false
 
@@ -47,6 +48,9 @@ function main () {
             break
         }
         break
+      case "--preid":
+        identifier = argv.shift()
+        break
       case "-r": case "--range":
         range.push(argv.shift())
         break
@@ -88,7 +92,7 @@ function success () {
   }).map(function (v) {
     return semver.clean(v, loose)
   }).map(function (v) {
-    return inc ? semver.inc(v, inc, loose) : v
+    return inc ? semver.inc(v, inc, loose, identifier) : v
   }).forEach(function (v,i,_) { console.log(v) })
 }
 
@@ -111,6 +115,10 @@ function help () {
               ,"        prepatch, or prerelease.  Default level is 'patch'."
               ,"        Only one version may be specified."
               ,""
+              ,"--preid <identifier>"
+              ,"        Identifier to be used to prefix premajor, preminor,"
+              ,"        prepatch or prerelease version increments."
+              ,""
               ,"-l --loose"
               ,"        Interpret versions and ranges loosely"
               ,""

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "semver",
-  "version": "3.0.1",
+  "version": "4.1.0",
   "description": "The semantic version parser used by npm.",
   "main": "semver.js",
   "browser": "semver.browser.js",