Closed indirect closed 10 months ago
I think the a
elements would have href
s rather than src
s ?
🤦🏻 you are correct, why did I write src
, these are not images.
Sorry for the late response, I missed this to review at high-level. :cry: Any reason to not make similar proposals RFC? I'm scanning RFC repo often for similar cases.
I started by looking at implementation and I have few questions to start with not related to the implementation itself (that's the reason to share in here, not in the implementation PR).
TL;DR unify gemspec metadata URIs and linksets
table, they are out of sync
I tried to understand how links are collected and stored, but I failed to follow the logic for now (I'll try later again). Looking at gemspec policy, following links are supported by specification policy.
# https://github.com/rubygems/rubygems/blob/2600ec81933c9ea59c5aa63abb051655208f669c/lib/rubygems/specification_policy.rb#L12-L21
METADATA_LINK_KEYS = %w[
bug_tracker_uri
changelog_uri
documentation_uri
homepage_uri
mailing_list_uri
source_code_uri
wiki_uri
funding_uri
].freeze # :nodoc:
Looking at linksets
table (used in initial implementation PR), not all of those URIs are stored in there.
linksets home
column is populated by spec.homepage
, for the rest I failed to find out where metadata are stored into linksets
table. But it seems to be somehow out of sync, not all metadata URIs are stored in linkset. It gets also little confusing since homepage could be specified in two ways in specification (spec.homepage
and spec.metadata['homepage_uri']
).
I did quick lookup how linkset table is populated and it seems homepage
is the only URI widely adopted (since it is required currently), see the stats bellow for more details. It could be partly caused by missing examples in generated gemspec. It would make sense to add all metadata links in gem template.
# https://github.com/rubygems/rubygems/blob/2600ec81933c9ea59c5aa63abb051655208f669c/bundler/lib/bundler/templates/newgem/newgem.gemspec.tt#L24-L26
spec.metadata["homepage_uri"] = spec.homepage
spec.metadata["source_code_uri"] = "TODO: Put your gem's public repo URL here."
spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
:thinking: I think it would be possible to start with unifying linkset and metadata URIs supported by RubyGems. Even the codebase is not sure about the proper place to find out some metadata and tries both metadata and linkset as a fallback.
Considering stats shared in previous block, let's focus on homepage only for now (to keep it simple). Most of the top domains used are hosted services with no way to change header value to pair with current way of verification. Currently it seems only github.com
and rubygems.org
are going to be supported.
It seems gitlab.com
and bitbucket.org
are good candidates to be included in initial implementation as well. Looking into mail
column, there groups.google.com
is the most used service. How to verify that one? The same question pops for docs
column often using rubydoc.info
I'm still not sure how useful is the whole verification process. What does verified mean for the user visiting rubygems.org page? Does it mean link is safe to follow? You can simply verify custom page and serve malicious content in there. Doesn't verification mark make false positive feeling that link is safe and verified by rubygems.org?
What about to infer metadata URIs for known services automatically? Let's say source_code_uri
is populated with github, if bug_tracker_uri
is not populated, we can check by API call if issues are enabled on the GitHub repo and automatically infer the URL. Same works for wiki, funding, changelog (scan for known changelog files like CHANGELOG.md, HISTORY.md, ...). That way we can really make those links safe. All needed is to somehow connect GitHub and RubyGems (using the same method as described in the original description). We can also make it somehow suggested to users (maybe with an email after initial push) with short explanation how to link those two together.
It would be possible to start just with GitHub URLs and add gitlab.com
and bitbucket.org
integration later. That would cover most of the cases.
Also what's proper homepage for common project with no real custom homepage? There's github.com
mostly used (~130k) and rubygems.org
(~9k). If I understand it well, homepage should be rubygems.org
and source_code_uri
should point to github.com
. Maybe we can make this suggestion into gem specification policy as well (to help assigning proper values).
Verified links would get a cool checkmark next to them on the gem show page sidebar, and maybe one day we can hide unverified links behind a click-through thing to make it clear that the owner of the website has not opted in to being listed on rubygems.org.
Each time a gem is pushed, and periodically after that (once a week, maybe?), we should fetch the HTML for the URL given and check for proof that the link is "verified". What does verified mean, you ask? I'm glad you asked.
We're going to borrow from the link-verification scheme that systems like Mastodon use, and look for links with a
rel
attribute. Here are some example links that would be valid:For URLs at
github.com
only, we would also accept links like:That would allow us to verify repos with the repo settings website value set to the rubygems.org gem URL.