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.

Sign up for GitHub

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

Proposal: Add homepage_url #92

Closed
wants to merge 1 commit into from
Closed

Proposal: Add homepage_url #92

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
7 changes: 7 additions & 0 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -91,6 +91,8 @@ The defintion for each components is:
- **version**: the version of the package. Optional.
- **qualifiers**: extra qualifying data for a package such as an OS,
architecture, a distro, etc. Optional and type-specific.
Multiple qualifiers must be separated with "&" and the keys should be
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you mind to put that in a separate PR?
I agree that some improvement would be welcomed there, but you definition may conflict with the spec:

In https://github.com/package-url/purl-spec/tree/ef3fa021b54e3e6014bc6d435cc497db030e234b#how-to-build-purl-string-from-its-components we have:

sort this list of qualifier strings lexicographically

And in https://github.com/package-url/purl-spec/tree/ef3fa021b54e3e6014bc6d435cc497db030e234b#a-purl-is-a-url

purl qualifiers: this maps to a URL query

So all in all IMHO we could in this area avoid reference to sorting and just introduce that qualifiers are key=value pairs separated by & using the same syntax as a URL query.

And add a mention about sorting being the "canonical" form in the qualifiers definition in https://github.com/package-url/purl-spec/tree/ef3fa021b54e3e6014bc6d435cc497db030e234b#rules-for-each-purl-component ?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pombredanne - a separate PR would be great! I probably should have done that anyway.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At this stage the latest spec states:

This is a query string composed of zero or more key=value pairs each separated by a '&' ampersand. A key and value are separated by the equal '=' character

Therefore I think we are good wrt. the first part of this PR which is about Multiple qualifiers must be separated with "&"

sorted by key in the "C" locale.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

BTW, just a side note for the wording for this new PR: sorted by key in the "C" locale. should be clarified and/or simplified. Also I am not sure this needs to be made so prominent as we do not provide so much details at that level for other components.
Note that the purl is already specified as being ASCII-only and the qualifier sorting is stated as sort this list of qualifier strings lexicographically which would be clear with ASCII and unambiguous as the keys are specified as being lowercase only, and there cannot be two qualifiers with the same key. This boils down to sorting digits first in ascending numeric order then letters in alphabetic order which is alright the C locale, but is also quite simply the default sort order in Python, Ruby, JavaScript. If we introduce the "C" locale there is a bit more complexity to process.

But to your point making the syntax and sorting should be made more prominent, likely under the "Rules for each purl component/qualifiers"

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Sorted by key lexicographically" is better than being unstated. I was trying for maximum precision. As long as there are only ASCII digits and lowercase letters I think locale doesn't matter, though there may be an exception.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we are good with lexicographic sorting (being a fancy word for alphabetical/alphanumeric) as we have only ASCII as specified. This was not raised as an issue since so we are good this way. I found that invoking a "C" locale has been raising more questions and head scratching that help

- **subpath**: extra subpath within a package, relative to the package root.
Optional.

Expand Down Expand Up @@ -580,6 +582,11 @@ candidate list further down.
the `generic` type and eventually contributed back to this specification
- as for other `type`, the `name` component is mandatory. In the worst case
it can be a file or directory name.
- A `homepage_url` may be provided in `qualifiers`; this identifies the
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM! I can merge alright but without the qualifiers part if that's OK with you.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't understand what you mean by "without the qualifiers part". It needs to go somewhere, and presumably that would be in the qualifiers. If you just think it's clear from context, I guess that's fine as long as it's clear. We all want a clear spec :-).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry if this came out as not really clear: by "without the qualifiers part" I meant without the part about qualifiers above https://github.com/package-url/purl-spec/pull/92/files#r504010637 that would be best in a separate PR.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh I see! Sure, that'd be great. Improvements are improvements.

main "home page" for users to learn more about the software.
This is especially useful when no public `download_url` and `vcs_url`
are available. It's also useful to help users find the correct
package home page.
- Examples (truncated for brevity)::

pkg:generic/[email protected]
Expand Down