From 3669b6e9230a8079fd84af3b20472b8ff29e85b5 Mon Sep 17 00:00:00 2001 From: "Kunz, Immanuel" Date: Tue, 12 Nov 2024 11:50:44 +0100 Subject: [PATCH 1/7] add ecosystem-independent all and none scheme, fix some typos --- VERSION-RANGE-SPEC.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/VERSION-RANGE-SPEC.rst b/VERSION-RANGE-SPEC.rst index 31c6dfb1..498a53c1 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) can 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 @@ -637,6 +641,8 @@ These are a few known versioning schemes for some common Package URL - **alpine**: Alpine linux https://gitlab.alpinelinux.org/alpine/apk-tools/-/blob/master/src/version.c which is using Gentoo-like conventions. +- **ecosystem-independent versioning schemes**: Several versioning schemes that are independent from any specific ecosystem are being developed. A very simple one is the generic *all* and *none* scheme which allows to specify that all (or none) of the versions are affected. + - **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) From 179e5ea0fcba4f8da9afb2aed7045074ff9a1dd8 Mon Sep 17 00:00:00 2001 From: "Kunz, Immanuel" Date: Thu, 14 Nov 2024 16:37:09 +0100 Subject: [PATCH 2/7] resolve tschmidtb51 comments Signed-off-by: Kunz, Immanuel --- VERSION-RANGE-SPEC.rst | 43 +++++++++++++++++++++++------------------- 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/VERSION-RANGE-SPEC.rst b/VERSION-RANGE-SPEC.rst index 498a53c1..ddad68bf 100644 --- a/VERSION-RANGE-SPEC.rst +++ b/VERSION-RANGE-SPEC.rst @@ -240,7 +240,7 @@ 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) can be specified: +Additionally, all versions (or none) SHOULD be specified: - ``vers:all/*`` - ``vers:none/*`` @@ -603,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 archlinux Pacman. - - **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 @@ -624,31 +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. - -- **maven**: Apache Maven supports a math interval notation which is rarely seen - in practice http://maven.apache.org/enforcer/enforcer-rules/versionRanges.html +- **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. -- **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) +TODO: add Rust, composer and archlinux, nginx, tomcat, apache. -- **gentoo**: Gentoo https://wiki.gentoo.org/wiki/Version_specifier -- **alpine**: Alpine linux https://gitlab.alpinelinux.org/alpine/apk-tools/-/blob/master/src/version.c - which is using Gentoo-like conventions. +Moreover, there are several versioning schemes that are independent from any specific ecosystem. -- **ecosystem-independent versioning schemes**: Several versioning schemes that are independent from any specific ecosystem are being developed. A very simple one is the generic *all* and *none* scheme which allows to specify that all (or none) of the versions are affected. +- **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: From 964736cdb642b4ce3c5c81fb3fcc7970f50cb844 Mon Sep 17 00:00:00 2001 From: "Kunz, Immanuel" Date: Fri, 15 Nov 2024 08:44:36 +0100 Subject: [PATCH 3/7] fix double ticks Signed-off-by: Kunz, Immanuel --- VERSION-RANGE-SPEC.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/VERSION-RANGE-SPEC.rst b/VERSION-RANGE-SPEC.rst index ddad68bf..d07e0334 100644 --- a/VERSION-RANGE-SPEC.rst +++ b/VERSION-RANGE-SPEC.rst @@ -646,13 +646,13 @@ TODO: add Rust, composer and archlinux, nginx, tomcat, apache. Moreover, there are several versioning schemes that are independent from any specific ecosystem. -- **all**: a generic versioning scheme where every version is inside the range, i.e., all versions match. This is equivalent to `true`. +- **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`. +- **none**: a generic versioning scheme where no version is inside the range, i.e. no versions match. This is equivalent to ``false``. A separate document will provide details for each versioning scheme and: From bd6bd1c06ccd1ffe79a02dfa73c5a5c4c6910d48 Mon Sep 17 00:00:00 2001 From: "Kunz, Immanuel" Date: Tue, 12 Nov 2024 11:50:44 +0100 Subject: [PATCH 4/7] add ecosystem-independent all and none scheme, fix some typos --- VERSION-RANGE-SPEC.rst | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/VERSION-RANGE-SPEC.rst b/VERSION-RANGE-SPEC.rst index b53ed5ca..e421bf17 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) can 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 @@ -637,6 +641,8 @@ These are a few known versioning schemes for some common Package URL - **alpine**: Alpine linux https://gitlab.alpinelinux.org/alpine/apk-tools/-/blob/master/src/version.c which is using Gentoo-like conventions. +- **ecosystem-independent versioning schemes**: Several versioning schemes that are independent from any specific ecosystem are being developed. A very simple one is the generic *all* and *none* scheme which allows to specify that all (or none) of the versions are affected. + - **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) From b9e994612dc33bc3833826fee3bbb26290c04638 Mon Sep 17 00:00:00 2001 From: "Kunz, Immanuel" Date: Thu, 14 Nov 2024 16:37:09 +0100 Subject: [PATCH 5/7] resolve tschmidtb51 comments Signed-off-by: Kunz, Immanuel --- VERSION-RANGE-SPEC.rst | 45 +++++++++++++++++++++++------------------- 1 file changed, 25 insertions(+), 20 deletions(-) diff --git a/VERSION-RANGE-SPEC.rst b/VERSION-RANGE-SPEC.rst index e421bf17..a4837bd2 100644 --- a/VERSION-RANGE-SPEC.rst +++ b/VERSION-RANGE-SPEC.rst @@ -240,7 +240,7 @@ 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) can be specified: +Additionally, all versions (or none) SHOULD be specified: - ``vers:all/*`` - ``vers:none/*`` @@ -603,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 @@ -624,31 +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. - -- **maven**: Apache Maven supports a math interval notation which is rarely seen - in practice http://maven.apache.org/enforcer/enforcer-rules/versionRanges.html +- **rpm**: RPM distros https://rpm-software-management.github.io/rpm/manual/dependencies.html + The simplified rmpvercmp version comparison routine is used by archlinux Pacman. -- **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) +TODO: add Rust, composer and archlinux, nginx, tomcat, apache. -- **gentoo**: Gentoo https://wiki.gentoo.org/wiki/Version_specifier -- **alpine**: Alpine linux https://gitlab.alpinelinux.org/alpine/apk-tools/-/blob/master/src/version.c - which is using Gentoo-like conventions. +Moreover, there are several versioning schemes that are independent from any specific ecosystem. -- **ecosystem-independent versioning schemes**: Several versioning schemes that are independent from any specific ecosystem are being developed. A very simple one is the generic *all* and *none* scheme which allows to specify that all (or none) of the versions are affected. +- **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: From 01215fb3d251c37c108de6cc1953e46974570637 Mon Sep 17 00:00:00 2001 From: "Kunz, Immanuel" Date: Fri, 15 Nov 2024 08:44:36 +0100 Subject: [PATCH 6/7] fix double ticks Signed-off-by: Kunz, Immanuel --- VERSION-RANGE-SPEC.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/VERSION-RANGE-SPEC.rst b/VERSION-RANGE-SPEC.rst index a4837bd2..17f3171e 100644 --- a/VERSION-RANGE-SPEC.rst +++ b/VERSION-RANGE-SPEC.rst @@ -646,13 +646,13 @@ TODO: add Rust, composer and archlinux, nginx, tomcat, apache. Moreover, there are several versioning schemes that are independent from any specific ecosystem. -- **all**: a generic versioning scheme where every version is inside the range, i.e., all versions match. This is equivalent to `true`. +- **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`. +- **none**: a generic versioning scheme where no version is inside the range, i.e. no versions match. This is equivalent to ``false``. A separate document will provide details for each versioning scheme and: From 5248947e15ab152f5debf2221f8c98908517d722 Mon Sep 17 00:00:00 2001 From: "Kunz, Immanuel" Date: Fri, 15 Nov 2024 12:04:25 +0100 Subject: [PATCH 7/7] add semver 2.0 info to version-range-spec Signed-off-by: Kunz, Immanuel --- VERSION-RANGE-SPEC.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/VERSION-RANGE-SPEC.rst b/VERSION-RANGE-SPEC.rst index c8902a2f..80fd2faa 100644 --- a/VERSION-RANGE-SPEC.rst +++ b/VERSION-RANGE-SPEC.rst @@ -654,6 +654,8 @@ Moreover, there are several versioning schemes that are independent from any spe - **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/ + A separate document will provide details for each versioning scheme and: