doc: incomplete documentation for vanity import paths in combination with Go modules

[dominikh]

https://go.dev/ref/mod#vcs documents the <meta> tag that needs to be hosted at the module path, with the concrete example of golang.org/x/mod. However, it doesn't document how the module path is determined, and which pages need to exist for that process. For example, a user can do go get golang.org/x/mod/zip in module mode. The documentation doesn't state whether https://golang.org/x/mod/zip?go-get=1 needs to serve the meta tag or not.

Some vanity paths, like gioui.org suggest that these subpages don't have to exist, and that go get walks up the path until it gets a successful response that specifies the module path.

For example, GOPROXY=direct go get gioui.org/widget/material sends requests to the following URLs:

# get https://gioui.org/widget/material?go-get=1
# get https://gioui.org/widget?go-get=1
# get https://gioui.org/?go-get=1
# get https://gioui.org/widget?go-get=1: 404 Not Found (0.198s)
# get https://gioui.org/widget/material?go-get=1: 404 Not Found (0.200s)
# get https://gioui.org/?go-get=1: 200 OK (0.201s)

Out of these, only https://gioui.org/?go-get=1 responds with a meta tag.

https://pkg.go.dev/cmd/go@go1.21rc2#hdr-Remote_import_paths also contains documentation on vanity import paths, but doesn't discuss module paths. It does suggest, however, that only one request — to the full import path — is being made:

If the import path is not a known code hosting site and also lacks a version control qualifier, the go tool attempts to fetch the import over https/http and looks for a tag in the document's HTML .

This doesn't match the actual behavior of go get in module mode, but it does match go get in GOPATH mode. In fact, the previous example using gioui.org doesn't work in GOPATH mode, because gioui.org only serves the required meta tags for module paths, not for all possible import paths.

# get https://gioui.org/widget/material?go-get=1
# get https://gioui.org/widget/material?go-get=1: 404 Not Found (0.192s)
package gioui.org/widget/material: unrecognized import path "gioui.org/widget/material": reading https://gioui.org/widget/material?go-get=1: 404 Not Found
        server response: no such package

It would be nice to clarify, in the documentation, whether one can rely on the fact that go get walks up the import path until it finds the module path. Assuming that one can, it would also be interesting to explore whether it's acceptable to do so, as that only works for modules, not GOPATH.

[cagedmantis]

cc/ @bcmills @matloob

[bcmills]

https://pkg.go.dev/cmd/go@go1.21rc2#hdr-Remote_import_paths also contains documentation on vanity import paths, but doesn't discuss module paths.

That section does seem to be out of date; it describes the behavior in GOPATH mode. We should condense it and consider deleting it altogether. (Note that #60915 proposes to preserve the ability to build in GOPATH mode, but retire support for go get in GOPATH mode.)

It would be nice to clarify, in the documentation, whether one can rely on the fact that go get walks up the import path until it finds the module path.

See https://go.dev/ref/mod#resolve-pkg-mod.

Assuming that one can, it would also be interesting to explore whether it's acceptable to do so, as that only works for modules, not GOPATH.

That depends entirely on whether you want your module to be compatible with GOPATH mode. (I would argue that that is unnecessary, especially for new code — but ultimately the package author gets to decide what they want to support.)

[dominikh]

See https://go.dev/ref/mod#resolve-pkg-mod.

That's helpful, thanks. I think it would make sense to refer to that in https://go.dev/ref/mod#vcs for people like me, who only read that section and not the whole document.

[shani34]

hi, can someone please assign this issue to me