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.

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

cmd/go: improve `go help goproxy` #29009

Open
hyangah opened this issue Nov 29, 2018 · 9 comments
Assignees
Milestone

Comments

@hyangah
Copy link
Contributor

@hyangah hyangah commented Nov 29, 2018

'go help goproxy' describes the module proxy protocol, and it needs to document more details to guide correct proxy implementation.

  1. 'go get; issues a /latest query to go proxy, (https://go.googlesource.com/go/+/master/src/cmd/go/internal/modfetch/proxy.go#185) but this type of query is not documented.

  2. document what's the expected results for for non modules.
    For example, what's the expected results or error code for the following module or package?

 
   golang.org/x/tools/@v/list
   golang.org/x/tools/@latest
   golang.org/x/tools/go/@latest

   github.com/rogpeppe/godef/go/@v/list
   github.com/rogpeppe/godef/go/@latest
  1. specify appropriate error codes the go command expects for various error conditions.

@bcmills @rsc

@bcmills bcmills added the NeedsFix label Nov 29, 2018
@bcmills bcmills self-assigned this Nov 29, 2018
@bcmills bcmills added this to the Go1.12 milestone Nov 29, 2018
@bcmills

This comment has been minimized.

Copy link
Member

@bcmills bcmills commented Nov 29, 2018

@bcmills bcmills added the modules label Nov 29, 2018
@hyangah

This comment has been minimized.

Copy link
Contributor Author

@hyangah hyangah commented Nov 29, 2018

@hyangah

This comment has been minimized.

Copy link
Contributor Author

@hyangah hyangah commented Dec 20, 2018

Is this still in go1.12 milestone?

Is it a possibility to get rid of the /@latest query in the protocol?
Would be nice if the document can help figuring out why go get (without -m) issues both list and latest queries.

> go get -v -d golang.org/x/tools/cmd/guru/serial
Fetching http://localhost:8080/golang.org/x/tools/cmd/guru/serial/@v/list
go: finding golang.org/x/tools/cmd/guru/serial latest
Fetching http://localhost:8080/golang.org/x/tools/cmd/guru/serial/@latest
Fetching http://localhost:8080/golang.org/x/tools/cmd/guru/serial/@v/list
Fetching http://localhost:8080/golang.org/x/tools/cmd/guru/@v/list
go: finding golang.org/x/tools/cmd/guru latest
Fetching http://localhost:8080/golang.org/x/tools/cmd/guru/@latest
Fetching http://localhost:8080/golang.org/x/tools/cmd/guru/@v/list
Fetching http://localhost:8080/golang.org/x/tools/cmd/@v/list
go: finding golang.org/x/tools/cmd latest
Fetching http://localhost:8080/golang.org/x/tools/cmd/@latest
Fetching http://localhost:8080/golang.org/x/tools/cmd/@v/list
Fetching http://localhost:8080/golang.org/x/tools/@v/list
go: finding golang.org/x/tools v0.0.0-20181212200058-49db546f375e
Fetching http://localhost:8080/golang.org/x/tools/@v/v0.0.0-20181212200058-49db546f375e.info
go: downloading golang.org/x/tools v0.0.0-20181212200058-49db546f375e
Fetching http://localhost:8080/golang.org/x/tools/@v/v0.0.0-20181212200058-49db546f375e.zip
go: extracting golang.org/x/tools v0.0.0-20181212200058-49db546f375e
Fetching http://localhost:8080/golang.org/x/tools/@v/v0.0.0-20181212200058-49db546f375e.mod
@marwan-at-work

This comment has been minimized.

Copy link
Contributor

@marwan-at-work marwan-at-work commented Dec 20, 2018

Ops, I've missed the cc notification on this one.

So I opened a CL a while ago (https://go-review.googlesource.com/c/go/+/126615) that updated the documentation and @bcmills suggested to look at potentially removing @latest endpoint from the GOPROXY contract.

From what I know, having @latest is a nice separation from @v/list because @latest has one clear intention: give me the latest pseudo version that is available in the "upstream"

@v/list on the other hand can be one of a few things: maybe a GOPROXY only wants to list certain versions, maybe it wants a combination of upstream and whatever it has stored, etc.

GOPROXY implementers therefore, can easily miss the fact that when the implement their own @v/list endpoint, that that they have to go to upstream and get the latest commit sha and turn it into a pseudo version, and then lump it with the other versions.

BTW, go list -m -versions -json gives you a "Latest" and a "Versions" response accordingly.

@hyangah

This comment has been minimized.

Copy link
Contributor Author

@hyangah hyangah commented Dec 20, 2018

Thanks @marwan-at-work for the explanation. Can you update your cl to mention this bug?

One minor thing - If the @latest query corresponds to the 'Version' field of the go list -m -json output, it doesn't necessarily mean the latest pseudo version.

> go list -m -versions -json golang.org/x/textgo: finding golang.org/x/text v0.3.0
{
	"Path": "golang.org/x/text",
	"Version": "v0.3.0",
	"Versions": [
		"v0.1.0",
		"v0.2.0",
		"v0.3.0"
	],
	"Time": "2017-12-14T13:08:43Z"
}

vs.

go list -m -versions -json golang.org/x/text@master
go: finding golang.org/x/text master
{
	"Path": "golang.org/x/text",
	"Version": "v0.0.0-20181211190257-17bcc049122f",
	"Versions": [
		"v0.1.0",
		"v0.2.0",
		"v0.3.0"
	],
	"Time": "2018-12-11T19:02:57Z"
}

I don't know why the pseudo version picks up v0.0.0 instead of v0.3.0 (maybe related to #29262).

@marwan-at-work

This comment has been minimized.

Copy link
Contributor

@marwan-at-work marwan-at-work commented Dec 20, 2018

@hyangah this is because you specified @master explicitly. You're looking to get the latest from that branch, therefore you get the pseudo version (note it's not really v0.0.0 but v0.0.0-20181211190257-17bcc049122f which denotes the "latest" commit from master.

But good call out, go list will give you the latest semver tag, unless there are no tags. Similarly, the go command will pick the latest version from @v/list and not ping @latest unless @v/list returns an empty list.

@gopherbot

This comment has been minimized.

Copy link

@gopherbot gopherbot commented Dec 20, 2018

Change https://golang.org/cl/126615 mentions this issue: cmd/go/internal/modfetch: update proxy usage

@hyangah

This comment has been minimized.

Copy link
Contributor Author

@hyangah hyangah commented Dec 20, 2018

Looking again into the go list -m -json -versions output, there is no "Latest" field. I think the "Version" field indicates the version the main module is using (so in the module cache) or specified version, not the latest.

So, I am still not sure what's the purpose of this latest query.

Regarding the v0.0.0 comment, I meant the prefix used to generate the pseudo version.

@gopherbot

This comment has been minimized.

Copy link

@gopherbot gopherbot commented Jan 14, 2019

Change https://golang.org/cl/157800 mentions this issue: cmd/go: improve goproxy and list documentation

@andybons andybons modified the milestones: Go1.12, Go1.13 Feb 12, 2019
@andybons andybons modified the milestones: Go1.13, Go1.14 Jul 8, 2019
@rsc rsc modified the milestones: Go1.14, Backlog Oct 9, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
6 participants
You can’t perform that action at this time.