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

Closed
hyangah opened this issue Nov 29, 2018 · 10 comments
Closed

cmd/go: improve go help goproxy #29009

hyangah opened this issue Nov 29, 2018 · 10 comments
Labels
Documentation FrozenDueToAge modules NeedsFix The path to resolution is known, but the work has not been done.
Milestone

Comments

@hyangah
Copy link
Contributor

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 The path to resolution is known, but the work has not been done. 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
Copy link
Contributor

bcmills commented Nov 29, 2018

CC @marwan-at-work

@hyangah
Copy link
Contributor Author

hyangah commented Nov 29, 2018

@ianthehat

@hyangah
Copy link
Contributor Author

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
Copy link
Contributor

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
Copy link
Contributor Author

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
Copy link
Contributor

@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
Copy link

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

@hyangah
Copy link
Contributor Author

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
Copy link

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
@hyangah
Copy link
Contributor Author

hyangah commented Jan 5, 2022

Let's close this since now there is a comprehensive set of documentation about modules.

@hyangah hyangah closed this as completed Jan 5, 2022
@rsc rsc unassigned bcmills Jun 23, 2022
@golang golang locked and limited conversation to collaborators Jun 23, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
Documentation FrozenDueToAge modules NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Development

No branches or pull requests

6 participants