cmd/go: document 'internal' package visibility for module mode

[wozz]

What version of Go are you using (go version)?

$ go version
go version go1.14.2

Does this issue reproduce with the latest release?

yes

What operating system and processor architecture are you using (go env)?

go env Output

$ go env

What did you do?

https://play.golang.org/p/tnQdiMMclCx

What did you expect to see?

I expected the program to compile.

What did you see instead?

prog.go:7:2: use of internal package example.com/v2/internal/foo not allowed

[andybons]

@bcmills @jayconrod @matloob

[bcmills]

The error message here is correct.

In order for an internal package to be imported, the package containing the import statement must have the same prefix as the internal package up to the last /internal/ element.

In this case, that prefix is example.com/v2, which is not a prefix of example.com/test.

If you want an internal package to be shared between example.com/test and example.com/v2, it must be within module example.com (or, rarely, some other module that begins with example.com/internal — but I would not recommend that if you can avoid it).

[bcmills]

This behavior is documented in go help gopath, although it appears that we need to update that documentation to be more explicit about how it maps to module mode.

[abemotion]

Each different major version (v1, v2, and so on) of a Go module uses a different module path.
In the example, v2 of foo is no longer foo: instead, it is identified by the module path foo/v2.

Adding This documentation to go help gopath is better ?

[gopherbot]

Change https://golang.org/cl/243398 mentions this issue: cmd/go: improve gopath documentation about internal directories

[gopherbot]

Change https://go.dev/cl/475640 mentions this issue: cmd/go: move module info up in GOPATH help