cmd/go: improve error message for mismatched major versions

[glycerine]

related to
#35732
which remains the top google hit for this error

what does one do to get this simple example to work?

jaten@jatens-MacBook-Pro ~/etcd-embed $ go build
go: errors parsing go.mod:
/Users/jaten/etcd-embed/go.mod:3: require go.etcd.io/etcd: version "v3.4.13" invalid: module contains a go.mod file, so major version must be compatible: should be v0 or v1, not v3
jaten@jatens-MacBook-Pro ~/etcd-embed $ go version
go version go1.14.4 darwin/amd64
jaten@jatens-MacBook-Pro ~/etcd-embed $ cat go.mod
module github.com/glycerine/etcd-embed

require go.etcd.io/etcd v3.4.13
                                      
go 1.14

          
jaten@jatens-MacBook-Pro ~/etcd-embed $ cat main.go
package main

import (
	"log"
	"time"

	"go.etcd.io/etcd/v3/embed"
)

func main() {
	cfg := embed.NewConfig()
	cfg.Dir = "default.etcd"
	e, err := embed.StartEtcd(cfg)
	if err != nil {
		log.Fatal(err)
	}
	defer e.Close()
	select {
	case <-e.Server.ReadyNotify():
		log.Printf("Server is ready!")
	case <-time.After(60 * time.Second):
		e.Server.Stop() // trigger a shutdown
		log.Printf("Server took too long to start!")
	}
	log.Fatal(<-e.Err())
}
jaten@jatens-MacBook-Pro ~/etcd-embed $

if I change go.mod to

module github.com/glycerine/etcd-embed

require go.etcd.io/etcd/v3 v3.4.13

go 1.14

I get the equally mystifying

jaten@jatens-MacBook-Pro ~/etcd-embed $ go build
go: go.etcd.io/etcd/[email protected]: go.mod has non-.../v3 module path "go.etcd.io/etcd" (and .../v3/go.mod does not exist) at revision v3.4.13
jaten@jatens-MacBook-Pro ~/etcd-embed $

[andig]

Imho v3 denotes a v3 major module version. Seems your module in question is v1 (although it has a 3.xyz version number), so omit the /v3 suffix when requiring it. While this sounds confusing it is imho due to keeping backwards compatibility with modules what introduced versioning before go.mod came around in go 1.11.

[andig]

Imho you need to change the module path to the github-hosted one which declares itself as v3.

[bcmills]

As noted in #35732 (comment):

[W]e do want to make the errors as clear as possible. If you have a specific improvement to suggest in the phrasing of the error, please open a new issue (or send a change with the proposed improvement)!

That said, I've been thinking about this particular error message some more. I think the error message we've written today assumes that the module path is correct and the version is wrong (because it doesn't match the module path), when really most users who encounter this error really have written the version they intend: we should suggest a fix to the path, not to the version.

CC @jayconrod @matloob

[bcmills]

@glycerine, in this case, the problem is that the latest v3-tagged release of go.etcd.io/etcd (v3.4.13) has declared the wrong module path for that major version (it should instead be go.etcd.io/etcd/v3). That issue has been fixed at head (etcd-io/etcd@96cce20), but not yet included in a tagged release. (That is etcd-io/etcd#12068 / etcd-io/etcd#12109.)

The go command intentionally does not try untagged commits when a release tag exists for the requested major version, but you could fetch such a commit explicitly using go get -d go.etcd.io/etcd/v3@master.

[Skarlso]

@bcmills This has tripped me off several times already, so if we could make this more clear I would be delighted to create a CL with a clearer message.

[dzrtc]

That said, I've been thinking about this particular error message some more. I think the error message we've written today assumes that the module path is correct and the version is wrong (because it doesn't match the module path), when really most users who encounter this error really have written the version they intend: we should suggest a fix to the path, not to the version.

@bcmills I can appreciate that this situation puts the tooling into a dark room with little content to draw from to understand what's going on or how to inform the user. Go error messages are typically terse, but perhaps verbosity is called for here. Consider whether it would actually be easier to describe the error state if there wasn't an implicit assumption that error messages need be short.

For example, include several examples, include a link to that paper you've previously linked to regarding module versions, include corrections for real-world variations of this problem, etc. A good technical writer might be helpful here.

[bcmills]

A good technical writer might be helpful here.

That would be @stevetraut. 🙂

[icholy]

Maybe something like this?

require go.etcd.io/etcd: version "v3.4.13" invalid: module contains a go.mod file, so path must contain major version: should be go.etcd.io/etcd/v3

[dzrtc]

@icholy This advice is better but would not address the situation that happened to me (see "Getting the Major Version Fails" at comment #35732 (comment)).

[icholy]

@dzrtc

$ go get -u github.com/golang-migrate/migrate@v4
go get github.com/golang-migrate/migrate@v4: no matching versions for query "v4"

I checked http://github.com/golang-migrate/migrate and it doesn't have a branch or tag called v4. What do you find confusing about this error?

[gopherbot]

Change https://golang.org/cl/378400 mentions this issue: cmd/go/internal/modfetch: do not short-circuit canonical versions