cmd/go: complete documentation for module code layout

[grantwwu]

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

$ go version
go version go1.12 darwin/amd64

Does this issue reproduce with the latest release?

I believe 1.12 is the latest release

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

go env Output

$ go env
GOARCH="amd64"
GOBIN=""
GOCACHE="/Users/grant.wu/Library/Caches/go-build"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="darwin"
GOOS="darwin"
GOPATH="/Users/grant.wu/go"
GOPROXY=""
GORACE=""
GOROOT="/usr/local/Cellar/go/1.12/libexec"
GOTMPDIR=""
GOTOOLDIR="/usr/local/Cellar/go/1.12/libexec/pkg/tool/darwin_amd64"
GCCGO="gccgo"
CC="clang"
CXX="clang++"
CGO_ENABLED="1"
GOMOD=""
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=/var/folders/rm/k4qc6x917tdf1ms2f8t2jw1h0000gp/T/go-build926919438=/tmp/go-build -gno-record-gcc-switches -fno-common"

Description

(I'm not following the bug template here because this is more of a documentation issue)

I have an internal library which needs to provide versions in multiple languages. So for example, the Python implementation lives in /python. I recently was given responsibility for the Golang implementation, which lives in /golang.

I have been having a lot of difficulties importing this library from another Go program I've been trying to migrate to Go modules. One thing I noticed ahead of time might be an issue is that the go.mod file isn't in the root of the git repo.

I asked around in the Go slack, and nobody was really sure whether this was going to be an issue. I eventually realized that an answer might lie in https://github.com/golang/go/wiki/Modules#faqs--multi-module-repositories. Someone in the Go slack (@heschik) said

I checked with someone who knows a lot about multi-module repos (way more than me, at least) and they said you have to prefix it with the subdirectory.

I think it should be better documented that the caveats here - needing to tag versions in a special way, etc. - also apply to any repo which doesn't have go.mod in the root directory, even if they only have a single Go module.

(I mean, if we want to have a broader discussion of whether or not we want to change this behavior somehow, this issue can also be the place for that).

[bcmills]

The documentation at https://golang.org/cmd/go/#hdr-Module_code_layout currently links to https://research.swtch.com/vgo-module, which does describe repo layout and tag prefixes.

That said, we should move (a concise version of) that information to cmd/go itself.

[thepudds]

I think the main tag prefix discussion from https://research.swtch.com/vgo-module:

In the major subdirectory convention, v2/ contains the module "my/thing/v2". A natural extension is to allow subdirectories not named for major versions. For example, we could add a blue/ subdirectory that contains the module "my/thing/blue", confirmed by a blue/go.mod file with that module path. In this case, the source control commit tags addressing that module would take the form blue/v1.x.x. Similarly, the tag blue/v2.x.x would address the blue/v2/ subdirectory. The existence of the blue/go.mod file excludes the blue/ tree from the outer my/thing module.

In the Go project, we intend to explore using this convention to allow repositories like golang.org/x/text to define multiple, independent modules. This lets us retain the convenience of coarse-grained source control but still promote different subtrees to v1 at different times.