-
Notifications
You must be signed in to change notification settings - Fork 145
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 spec for brew
package URLs
#281
base: master
Are you sure you want to change the base?
Conversation
Signed-off-by: William Woodruff <[email protected]>
CC @p-linnane @SMillerDev @colindean for thoughts as well 🙂 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
One major nit and a few non-blocking questions and suggestions
- The tap syntax is ``https://github.com/{org}/Homebrew-{tap}``, so | ||
``homebrew/core`` corresponds to the URL ``https://github.com/homebrew/homebrew-core``. | ||
- The ``name`` is the formula name. | ||
- The ``version`` is the formula version. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
question (non-blocking): When thinking about the examples below, I think you should clarify how purl spec should handle version-in-formula formulae.
As in, if I want PostgreSQL 12.17 (current release as of this posting), should the purl be
pkg:brew/postgresql@[email protected]
or
pkg:brew/[email protected]
and let whatever's reading the purl — Homebrew, ostensibly — figure out how that version maps to our major-version formulae?
I speculate only the latter is a valid purl, a safe assumption because I don't think it's a good idea to allow two @
in the purl.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for calling this out -- my read of the purl spec is that the name and other components are always URL-escaped, e.g. pkg:brew/postgresql@[email protected]
would actually be encoded as pkg:brew/postgresql%[email protected]
in a "wire format" context. So the purl should always unambiguously map to a package, without the end client having to do additional disambiguation work.
This is a readability sacrifice, but my (potentially wrong) understanding is that purls are mostly meant to show up only in machine-readable contexts anyways.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sigh, it's not pretty, but if that's the way it needs to be, so be it. If that's the case, I'd recommend adding an example with that…
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done! Looks like the other examples for other ecosystem purls also contain URL-escaping examples, so we're in-line here 🙂
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
pkg:brew/postgresql@[email protected]
is incorrect. The instructions for parsing a PURL (which not all implementations follow) say to split on @
from the right, so it should parse as you expect for Homebrew, but the spec says that @
must always be escaped when it's not being used as the delimiter before the version number. It'd definitely be good to have an example and maybe even call this out since it's common for people to install packages with names like this.
giterlizzi/perl-URI-PackageURL has name "postgresql" version "12" (and discards the "12.17")
maenchen/purl, sonatype/package-url-java have name "postgresql" version "[email protected]"
package-url/packageurl-js throws an error (I thought I saw a fix for this, but maybe the PR hasn't merged)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yep, I added @colindean's example below. Adding an explicit callout also makes sense to me; I'll add some language for that.
PURL-TYPES.rst
Outdated
- Qualifier ``tap_url``: for taps that are not on GitHub or otherwise require an explicit URL, | ||
this is the full URL to the tap. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
question (non-blocking): Should there be another parameter to name the tap? We use the named tap at work, e.g.
brew tap myco/brewhouse [email protected]:brew/house.git
and the formula, uh, myco-ctl
could have a purl
pkg:brew/myco/brewhouse/[email protected]:brew/house.git
and brew would know how to name the tap if it needed to be tapped, or perhaps
pkg:brew/myco/brewhouse/[email protected]:brew/house.git&tap_name=myco/brewhouse
or more simply
pkg:brew/[email protected]:brew/house.git&tap_name=myco/brewhouse
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
My 0.02c would be for your first form:
pkg:brew/myco/brewhouse/[email protected]:brew/house.git
I think that's unambiguous: the github.com/{org}/homebrew-{tap}
logic only applies when a tap_url
isn't present, so I think this is the shortest form that conveys all needed information. But maybe I've overlooked something?
Co-authored-by: Colin Dean <[email protected]>
Co-authored-by: Colin Dean <[email protected]>
Signed-off-by: William Woodruff <[email protected]>
- The tap syntax is ``https://github.com/{org}/Homebrew-{tap}``, so | ||
``homebrew/core`` corresponds to the URL ``https://github.com/homebrew/homebrew-core``. | ||
- The ``name`` is the formula name. | ||
- The ``version`` is the formula version. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Sigh, it's not pretty, but if that's the way it needs to be, so be it. If that's the case, I'd recommend adding an example with that…
Co-authored-by: Colin Dean <[email protected]>
Signed-off-by: William Woodruff <[email protected]>
@MikeMcQuaid 👋 A quick review or ack from you would awesome! |
Thanks! |
According to Stack Overflow, you cannot install a specific version. |
Both TL;DR yes, there is no way to install a specific minor version, e.g. postgres 16.1. Link for reference: https://github.com/Homebrew/homebrew-core/blob/master/Formula/p/postgresql%4016.rb |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks good to me!
Gentle ping for review+approval here: this is no longer a blocker in Homebrew's attestation work, but I'd like to get it in so that we can consider it for any future attestation changes, if necessary 🙂 |
Another gentle ping for review here! |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
+1 for merging this.
This adds the
brew
purl type.Closes #254.