(Edited: now a proposal.)
This issue describes a new HTML meta tag for referring to Go source files in online documentation. It is an official Go proposal, though it doesn't affect the Go language or tools.
For many years, the
We propose a new tag,
For certain common code-hosting sites, like GitHub and Bitbucket, no
For a module with path
After a tool replaces a template’s parameters, it should remove doubled and trailing slashes. This should make go-source’s
Any component of the tag’s contents can be omitted by using an underscore.
Here’s an example of the
Tools should derive
For a nested module,
Implicit Source Information
The templates for these sites are well-known, and are provided below.
There is one problem: for a major version greater than 1, the templates for “major branch” and “major subdirectory” conventions differ (See https://research.swtch.com/vgo-module for a discussion of these conventions.) To determine the right template, make a HEAD request for the
In these patterns, REPO is the repo URL and MS is the suffix of the module path without the repo prefix. These can be determined from the
Sites that won’t work
Code-hosting sites running Gitea cannot be accommodated by the source linking scheme described above, or indeed by any scheme that has only the information available from the module zip. Gitea source URLs are different for branches, tags and commit hashes, and for the last only the full hash will work. Since revisions should always be tags, the templates for a Gitea site can use the tag form of the source URL. But there is no template that will work with the abbreviated hash at the end of a pseudo-version.
While a source-browsing tool could clone the repo and resolve the abbreviated hash locally, that work should be outside the scope of the tool. Instead, we suggest that a gitea.com contributor add URL routes that can work with partial hashes.
The same problem exists for code.dumpstack.io (which appears to be a rebranded gitea).
Whatever software is used for https://blitiri.com.ar/ has the same issues, and one additional one: there doesn’t seem to be any URL for tags.
The text was updated successfully, but these errors were encountered:
You're right that it wouldn't need to affect
The base documentation for remote import paths, Go meta tags, and how to obtain them via
So I think my original wording wasn't right, but I still think this is very relevant to the folks who work on modules such as @bcmills or @jayconrod. What package to file this under would depend on where this would all be documented, I assume.
I also do think we should make this a proposal, since it seems like a pretty big decision to make without the process :)
The current convention is documented on the gddo repo's wiki. I don't know if the doc needs to live anywhere more prominent or central than that (with s/gddo/pkgsite/ of course).
Copy of #40477 (comment):
We identified a few important problems with the go-source-v2 idea, most notably:
This makes us pretty confident that go-source-v2 as proposed in the other issue is not the right long-term solution. It's a little bit more module-friendly in that it knows what a version is, but it's not module-friendly enough. More thought is clearly needed.
And even if we added that go-source-v2 support today, we'd need every go get redirector to be updated before any links would start working. That's a lot to ask for a design that we're not even sure is right, especially when a better design might not require any changes at all. The right answer might be to display the code directly from the zip files, or it might be to put some info in the zip file that helps find a source display, or it might be something else entirely. We don't know.
For now, instead of defining a new tag that will require widespread adoption but still not be completely right, it seems best to get the most common sites working by making changes to pkg.go.dev directly, and then revisit the topic when we've had more time to think about the right path forward.
For golang/go#39559 Change-Id: Id9c2ae0bcac9299565695d79a66f4bf591e60364 Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/274956 Trust: Jonathan Amsterdam <firstname.lastname@example.org> Run-TryBot: Jonathan Amsterdam <email@example.com> TryBot-Result: kokoro <firstname.lastname@example.org> Reviewed-by: Julie Qiu <email@example.com>
We changed the "known sites" approach to recognize specific URL schemas in the old version-free go-source tags and automatically adjust them to the versioned equivalents. That approach requires only O(number of hosting softwares) instead of O(number of hosting domains) cases and should scale better.
That change, along with our willingness to add custom patterns to the pkg.go.dev source as necessary to match new sites (see #40477), makes this proposal unnecessary. I retract it.