Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add semantic versioning info to version range spec #345

Open
wants to merge 8 commits into
base: master
Choose a base branch
from
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 34 additions & 21 deletions VERSION-RANGE-SPEC.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -620,29 +638,24 @@ 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``.

- **semver**: the semantic versioning scheme 2.0.0, defined in https://semver.org/

TODO: add Rust, composer and archlinux, nginx, tomcat, apache.

A separate document will provide details for each versioning scheme and:

Expand Down