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: complete documentation for module code layout #30850

grantwwu opened this issue Mar 14, 2019 · 2 comments

cmd/go: complete documentation for module code layout #30850

grantwwu opened this issue Mar 14, 2019 · 2 comments


Copy link

@grantwwu grantwwu commented Mar 14, 2019

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
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"


(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 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).

Copy link

@bcmills bcmills commented Mar 14, 2019

The documentation at currently links to, which does describe repo layout and tag prefixes.

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

@bcmills bcmills changed the title Document that go.mod should be in the repository root, even for single-module repos cmd/go: complete documentation for module code layout Mar 14, 2019
@bcmills bcmills added this to the Go1.13 milestone Mar 14, 2019
@bcmills bcmills added the NeedsFix label Mar 14, 2019
Copy link

@thepudds thepudds commented Mar 14, 2019

I think the main tag prefix discussion from

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 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
6 participants
You can’t perform that action at this time.