From 06546ad655d1416558b22c653b9a2399fecad6ea Mon Sep 17 00:00:00 2001 From: aristotelos Date: Tue, 17 Sep 2024 13:43:11 +0200 Subject: [PATCH 1/4] Address review comments Revive https://github.com/package-url/purl-spec/pull/245 by adding the following changes: - `registry_url` -> `repository_url` - `registry_version` -> `port_revision` - Remove percent escaping from `repository_url` to be more consistent with other uses of `repository_url` in the purl spec --- PURL-TYPES.rst | 31 ++++++++++--------------------- test-suite-data.json | 30 +++++++++++++++++++++--------- 2 files changed, 31 insertions(+), 30 deletions(-) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index e50497f..c9a6998 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -530,32 +530,21 @@ vcpkg - **port** - A package, along with it's build scripts and possibly minor modifications. - **registry** - A collection of ports, possibly private to the user. Analogous to **repository**. -- ``namespace``: Currently reserved for future use and should be empty - +- ``namespace``: Currently reserved for future use and should be empty. - ``name``: The case-sensitive name of the port. **Required** -- ``version``: The port version. **Required** -- ``qualifiers``: The qualifiers below are used to provide more specific information on a port's origin registry and to distinguish between multiple instances of the same port dependency within the same project (for example, when the project targets multiple platforms). - - - ``repository_url``: A `percent-encoded `_ absolute URI for the registry the port came from. For filesystem registries, the URI will have a `file` URI scheme. **Optional** - - - If empty, the port comes from the default registry, ``https://github.com/microsoft/vcpkg``. - - - ``registry_version``: A string specifying the version of the registry specified by `repository_url`. - - - For git registries, the commit hash (potentially abbreviated). This must __NOT__ be any other kind of git reference, such as `HEAD` or tags. **Required** - - For filesystem registries, an string that can be used to identify specific versions, such as Coordinated Universal Time (UTC) as described in `RFC 3339 `_. If using a UTC time, be sure to percent-encode it correctly. **Optional** - - - Additional qualifiers may be present on the purl that provide additional information about the context in which the package is being used, such as build configuration or platform information. These additional qualifiers must be tolerated during parsing and can be ignored if the parser does not expect them. - +- ``version``: The upstream version of the port (excluding the port file revision). **Required** - ``subpath``: Currently reserved for future use and should be empty. +- Qualifier ``repository_url``: The vcpkg registry where the package is available (optional). If omitted, ``https://github.com/microsoft/vcpkg`` as default registry is assumed. +- Qualifier ``port_revision``: A string specifying the [port file revision](https://learn.microsoft.com/en-us/vcpkg/reference/vcpkg-json#port-version) (optional). +- Additional qualifiers may be present on the purl that provide additional information about the context in which the package is being used, such as build configuration or platform information. These additional qualifiers must be tolerated during parsing and can be ignored if the parser does not expect them. - Examples:: - Microsoft GSL version 4.0.0 from the default registry at commit 4e2b371 - pkg:vcpkg/ms-gsl@4.0.0?registry_version=4e2b371 - ffmpeg version 5.1.2 from the azure-sdk registry at commit e6c17cc - pkg:vcpkg/ffmpeg@5.1.2?registry_url=https%3A%2F%2Fgithub.com%2Fazure-sdk%2Fvcpkg®istry_version=e6c17cc + Microsoft GSL version 4.0.0 from the default registry with port file revision 4 + pkg:vcpkg/ms-gsl@4.0.0?port_revision=4 + ffmpeg version 5.1.2 from the azure-sdk registry + pkg:vcpkg/ffmpeg@5.1.2?repository_url=https://github.com/azure-sdk/vcpkg LLVM from a filesystem registry - pkg:vcpkg/llvm@15.0.7?registry_url=file%3A%2F%2F%2FC%3A%2Flocal-registry%2Fvcpkg®istry_version=2023-08-18T22%3A28%3A52Z + pkg:vcpkg/llvm@15.0.7?repository_url=file:///C:/local-registry/vcpkg diff --git a/test-suite-data.json b/test-suite-data.json index cdc56a2..9ac332a 100644 --- a/test-suite-data.json +++ b/test-suite-data.json @@ -349,37 +349,49 @@ }, { "description": "simple vcpkg purl", - "purl": "pkg:vcpkg/ms-gsl@4.0.0?registry_version=4e2b371", - "canonical_purl": "pkg:vcpkg/ms-gsl@4.0.0?registry_version=4e2b371", + "purl": "pkg:vcpkg/ms-gsl@4.0.0", + "canonical_purl": "pkg:vcpkg/ms-gsl@4.0.0", "type": "vcpkg", "namespace": null, "name": "ms-gsl", "version": "4.0.0", - "qualifiers": {"registry_version": "4e2b371"}, + "qualifiers": null, + "subpath": null, + "is_invalid": false + }, + { + "description": "vcpkg with port_revision", + "purl": "pkg:vcpkg/ms-gsl@4.0.0?port_revision=4", + "canonical_purl": "pkg:vcpkg/ms-gsl@4.0.0?port_revision=4", + "type": "vcpkg", + "namespace": null, + "name": "ms-gsl", + "version": "4.0.0", + "qualifiers": {"port_revision": "4"}, "subpath": null, "is_invalid": false }, { "description": "vcpkg non-default git registry", - "purl": "pkg:vcpkg/ffmpeg@5.1.2?registry_url=https%3A%2F%2Fgithub.com%2Fazure-sdk%2Fvcpkg®istry_version=e6c17cc", - "canonical_purl": "pkg:vcpkg/ffmpeg@5.1.2?registry_url=https%3A%2F%2Fgithub.com%2Fazure-sdk%2Fvcpkg®istry_version=e6c17cc", + "purl": "pkg:vcpkg/ffmpeg@5.1.2?repository_url=https://github.com/azure-sdk/vcpkg&port_revision=3", + "canonical_purl": "pkg:vcpkg/ffmpeg@5.1.2?repository_url=https://github.com/azure-sdk/vcpkg&port_revision=3", "type": "vcpkg", "namespace": null, "name": "ffmpeg", "version": "5.1.2", - "qualifiers": {"registry_url": "https://github.com/azure-sdk/vcpkg", "registry_version": "e6c17cc"}, + "qualifiers": {"repository_url": "https://github.com/azure-sdk/vcpkg", "port_revision": "3"}, "subpath": null, "is_invalid": false }, { "description": "vcpkg filesystem registry", - "purl": "pkg:vcpkg/llvm@15.0.7?registry_url=file%3A%2F%2F%2FC%3A%2Flocal-registry%2Fvcpkg®istry_version=2023-08-18T22%3A28%3A52Z", - "canonical_purl": "pkg:vcpkg/llvm@15.0.7?registry_url=file%3A%2F%2F%2FC%3A%2Flocal-registry%2Fvcpkg®istry_version=2023-08-18T22%3A28%3A52Z", + "purl": "pkg:vcpkg/llvm@15.0.7?repository_url=file:///C:/local-registry/vcpkg", + "canonical_purl": "pkg:vcpkg/llvm@15.0.7?repository_url=file:///C:/local-registry/vcpkg", "type": "vcpkg", "namespace": null, "name": "llvm", "version": "15.0.7", - "qualifiers": {"registry_url": "file:///C:/local-registry/vcpkg", "registry_version": "2023-08-18T22:28:52Z"}, + "qualifiers": {"repository_url": "file:///C:/local-registry/vcpkg"}, "subpath": null, "is_invalid": false }, From b8bb1fac175eada1cdf1ff8cd0875d1cf847a3a4 Mon Sep 17 00:00:00 2001 From: aristotelos Date: Thu, 10 Oct 2024 07:43:11 +0200 Subject: [PATCH 2/4] Make URL language-inspecific Co-authored-by: Michael B. Price --- PURL-TYPES.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index c9a6998..427cf1a 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -535,7 +535,7 @@ vcpkg - ``version``: The upstream version of the port (excluding the port file revision). **Required** - ``subpath``: Currently reserved for future use and should be empty. - Qualifier ``repository_url``: The vcpkg registry where the package is available (optional). If omitted, ``https://github.com/microsoft/vcpkg`` as default registry is assumed. -- Qualifier ``port_revision``: A string specifying the [port file revision](https://learn.microsoft.com/en-us/vcpkg/reference/vcpkg-json#port-version) (optional). +- Qualifier ``port_revision``: A string specifying the [port file revision](https://learn.microsoft.com/vcpkg/reference/vcpkg-json#port-version) (optional). - Additional qualifiers may be present on the purl that provide additional information about the context in which the package is being used, such as build configuration or platform information. These additional qualifiers must be tolerated during parsing and can be ignored if the parser does not expect them. - Examples:: From 3e9339bdc70dacdb060c1355cbfd5da52396d134 Mon Sep 17 00:00:00 2001 From: aristotelos Date: Thu, 10 Oct 2024 08:37:50 +0200 Subject: [PATCH 3/4] Add optional `repository_revision` qualifier Add optional `repository_revision` so that mistakes in `port_revision` and `version` can be accounted for. Not relevant for filesystem registries or overlay ports because that gives no further external traceability. Along with this, describe the filesystem registries and overlay port cases. --- PURL-TYPES.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/PURL-TYPES.rst b/PURL-TYPES.rst index 427cf1a..a47af59 100644 --- a/PURL-TYPES.rst +++ b/PURL-TYPES.rst @@ -534,8 +534,9 @@ vcpkg - ``name``: The case-sensitive name of the port. **Required** - ``version``: The upstream version of the port (excluding the port file revision). **Required** - ``subpath``: Currently reserved for future use and should be empty. -- Qualifier ``repository_url``: The vcpkg registry where the package is available (optional). If omitted, ``https://github.com/microsoft/vcpkg`` as default registry is assumed. +- Qualifier ``repository_url``: The absolute URL of the vcpkg registry where the package is available (optional). If omitted, ``https://github.com/microsoft/vcpkg`` as default registry is assumed. For filesystem registries or [overlay ports](https://learn.microsoft.com/vcpkg/concepts/overlay-ports), the URI will have a `file` URI scheme. - Qualifier ``port_revision``: A string specifying the [port file revision](https://learn.microsoft.com/vcpkg/reference/vcpkg-json#port-version) (optional). +- Qualifier ``repository_revision``: The commit hash of the vcpkg registry, potentially abbreviated (optional). - Additional qualifiers may be present on the purl that provide additional information about the context in which the package is being used, such as build configuration or platform information. These additional qualifiers must be tolerated during parsing and can be ignored if the parser does not expect them. - Examples:: From 2ed3883c8038ffef8499d212aa36e07aba882c09 Mon Sep 17 00:00:00 2001 From: aristotelos Date: Thu, 10 Oct 2024 08:49:27 +0200 Subject: [PATCH 4/4] Extend test suite data Extend the port overlay or filesystem registry example with port revision. Add an example for additional qualifiers. --- test-suite-data.json | 20 ++++++++++++++++---- 1 file changed, 16 insertions(+), 4 deletions(-) diff --git a/test-suite-data.json b/test-suite-data.json index 9ac332a..31bc492 100644 --- a/test-suite-data.json +++ b/test-suite-data.json @@ -384,14 +384,26 @@ "is_invalid": false }, { - "description": "vcpkg filesystem registry", - "purl": "pkg:vcpkg/llvm@15.0.7?repository_url=file:///C:/local-registry/vcpkg", - "canonical_purl": "pkg:vcpkg/llvm@15.0.7?repository_url=file:///C:/local-registry/vcpkg", + "description": "vcpkg filesystem registry or overlay port", + "purl": "pkg:vcpkg/llvm@15.0.7?repository_url=file:///C:/local-registry/vcpkg&port_revision=3", + "canonical_purl": "pkg:vcpkg/llvm@15.0.7?repository_url=file:///C:/local-registry/vcpkg&port_revision=3", "type": "vcpkg", "namespace": null, "name": "llvm", "version": "15.0.7", - "qualifiers": {"repository_url": "file:///C:/local-registry/vcpkg"}, + "qualifiers": {"repository_url": "file:///C:/local-registry/vcpkg", "port_revision": "3"}, + "subpath": null, + "is_invalid": false + }, + { + "description": "vcpkg with additional qualifiers", + "purl": "pkg:vcpkg/ms-gsl@4.0.0?port_revision=4&repository_revision=42301df395&os=Linux&os_arch=x64&build_type=Debug&linkage=dynamic", + "canonical_purl": "pkg:vcpkg/ms-gsl@4.0.0?port_revision=4&repository_revision=42301df395&os=Linux&os_arch=x64&build_type=Debug&linkage=dynamic", + "type": "vcpkg", + "namespace": null, + "name": "ms-gsl", + "version": "4.0.0", + "qualifiers": {"port_revision": "4", "repository_revision": "42301df395", "os": "Linux", "os_arch": "x64", "build_type": "Debug", "linkage": "dynamic"}, "subpath": null, "is_invalid": false },