diff --git a/VERSION-RANGE-SPEC.rst b/VERSION-RANGE-SPEC.rst index b53ed5c..c8902a2 100644 --- a/VERSION-RANGE-SPEC.rst +++ b/VERSION-RANGE-SPEC.rst @@ -204,7 +204,7 @@ Using version range specifiers ``vers`` primary usage is to test if a version is within a range. -An version is within a version range if falls in any of the intervals defined +A version is within a version range if falls in any of the intervals defined by a range. Otherwise, the version is outside of the version range. Some important usages derived from this include: @@ -240,6 +240,10 @@ A list of versions, enumerated: - ``vers:pypi/0.0.0|0.0.1|0.0.2|0.0.3|1.0|2.0pre1`` +Additionally, all versions (or none) SHOULD be specified: + +- ``vers:all/*`` +- ``vers:none/*`` A complex statement about a vulnerability in a "maven" package that affects multiple branches each with their own fixed versions at @@ -270,7 +274,7 @@ pessimistic version constraint is expanded: URI scheme ~~~~~~~~~~ -The ``vers`` URI scheme is an acronym for "VErsion Range Specifier". +The ``vers`` URI scheme is an acronym for "VErsion Range Specifier". It has been selected because it is short, obviously about version and available for a future formal registration for this URI-scheme at the IANA registry. @@ -354,7 +358,7 @@ Normalized, canonical representation and validation ----------------------------------------------------- The construction and validation rules are designed such that a ``vers`` is -easier to read and understand by human and straight forward to process by tools, +easier to read and understand by humans and straightforward to process by tools, attempting to avoid the creation of empty or impossible version ranges. - Spaces are not significant and removed in a canonical form. For example @@ -529,7 +533,7 @@ Checking if a version is contained within a range To check if a "tested version" is contained within a version range: -- Start from a parsed a version range specifier with: +- Start from a parsed version range specifier with: - a versioning scheme - a list of constraints of comparator and version, sorted by version @@ -599,16 +603,30 @@ Some of the known versioning schemes These are a few known versioning schemes for some common Package URL `types` (aka. ``ecosystem``). +- **alpine**: Alpine linux https://gitlab.alpinelinux.org/alpine/apk-tools/-/blob/master/src/version.c + which is using Gentoo-like conventions. + +- **cpan**: Perl https://perlmaven.com/how-to-compare-version-numbers-in-perl-and-for-cpan-modules + - **deb**: Debian and Ubuntu https://www.debian.org/doc/debian-policy/ch-relationships.html Debian uses these comparators: <<, <=, =, >= and >>. -- **rpm**: RPM distros https://rpm-software-management.github.io/rpm/manual/dependencies.html - The a simplified rmpvercmp version comparison routine is used by Arch Linux Pacman. - -- **gem**: RubyGems https://guides.rubygems.org/patterns/#semantic-versioning +- **gem**: Rubygems https://guides.rubygems.org/patterns/#semantic-versioning which is similar to ``node-semver`` for its syntax, but does not use semver versions. +- **gentoo**: Gentoo https://wiki.gentoo.org/wiki/Version_specifier + +- **golang**: Go modules https://golang.org/ref/mod#versions use ``semver`` versions + with a specific minimum version resolution algorithm. + +- **maven**: Apache Maven supports a math interval notation which is rarely seen + in practice http://maven.apache.org/enforcer/enforcer-rules/versionRanges.html + +- **nuget**: NuGet https://docs.microsoft.com/en-us/nuget/concepts/package-versioning#version-ranges + Note that Apache Maven and NuGet are following a similar approach with a + math-derived intervals syntax as in https://en.wikipedia.org/wiki/Interval_(mathematics) + - **npm**: npm uses node-semver which is based on semver with its own range notation https://github.com/npm/node-semver#ranges A similar but different scheme is used by Rust @@ -620,29 +638,22 @@ These are a few known versioning schemes for some common Package URL - **pypi**: Python https://www.python.org/dev/peps/pep-0440/ -- **cpan**: Perl https://perlmaven.com/how-to-compare-version-numbers-in-perl-and-for-cpan-modules - -- **golang**: Go modules https://golang.org/ref/mod#versions use ``semver`` versions - with a specific minimum version resolution algorithm. +- **rpm**: RPM distros https://rpm-software-management.github.io/rpm/manual/dependencies.html + The a simplified rmpvercmp version comparison routine is used by archlinux Pacman. -- **maven**: Apache Maven supports a math interval notation which is rarely seen - in practice http://maven.apache.org/enforcer/enforcer-rules/versionRanges.html +TODO: add Rust, composer and archlinux, nginx, tomcat, apache. -- **nuget**: NuGet https://docs.microsoft.com/en-us/nuget/concepts/package-versioning#version-ranges - Note that Apache Maven and NuGet are following a similar approach with a - math-derived intervals syntax as in https://en.wikipedia.org/wiki/Interval_(mathematics) -- **gentoo**: Gentoo https://wiki.gentoo.org/wiki/Version_specifier +Moreover, there are several versioning schemes that are independent from any specific ecosystem. -- **alpine**: Alpine linux https://gitlab.alpinelinux.org/alpine/apk-tools/-/blob/master/src/version.c - which is using Gentoo-like conventions. +- **all**: a generic versioning scheme where every version is inside the range, i.e., all versions match. This is equivalent to ``true``. - **generic**: a generic version comparison algorithm (which will be specified later, likely based on a split on any wholly alpha or wholly numeric segments and dealing with digit and string comparisons, like is done in libversion) +- **none**: a generic versioning scheme where no version is inside the range, i.e. no versions match. This is equivalent to ``false``. -TODO: add Rust, composer and archlinux, nginx, tomcat, apache. A separate document will provide details for each versioning scheme and: