Go: cmd/go: document that module names without dots are reserved

[mvdan]

Intuitively, most Go developers publish Go code under import paths like foo.com/bar, not foo/bar. Often, this is just to make them reachable on the internet.

However, some have avoided the .tld entirely when working with local-only GOPATHS and modules. And this mostly works, as long as you're careful to not clash with an existing standard library package.

For example, I recall a recent issue in this tracker (which I can't find now!) where their GOPATH build broke when upgrading the Go version, as the root path element was plugin, which had been added to the standard library since.

An instance of this discussion happened last September, as pointed out by @bcmills. Quoting @rsc:

We want to allow experimentation, so we're not categorically cutting off all module statements in all contexts without dots, but anything that has to get resolved through downloading needs a dot and more generally should have a fully qualified domain name. That's how we've carved the name space between standard library and external things. I understand that pedantically the RFCs don't require dots but that's the separation we've used from very very early on with goinstall and later go get.

However, this separation isn't well documented anywhere. Even if we consider it as a warning or recommendation more than a strict rule, I think we should still mention it somewhere.

I also think we should encourage the use of .tld even if the module is for local use only, because of potential breakages with future Go builds. Perhaps a suggestion can be made, like .local.

Another advantage of strongly encouraging the use of .tld is that it's much easier to tell if a package is from the standard library or not. Without the separation, one would have to keep a list of all standard library package paths, which easily gets out of date. Or run go list std, which adds work.

Note that this doesn't need to change how cmd/go behaves; it's fine if a module name without a dot happens to build today.

[mvdan]

The title contains "modules", but I assume this would apply to the GOPATH mode too. That is, $GOPATH/src/foo/bar would be discouraged just like module foo/bar.

[andybons]

@bcmills @jayconrod

[mvdan]

Small detail I forgot - it's a dot in the first path element. foo.com/bar is fine as a non-reserved path, but foo/bar.baz technically isn't.

[mvdan]

Another small detail. It's not correct to say "all import paths without dots are reserved by the standard library", because there are a few counter-examples. Use go list foo.go, and you'll see command-line-arguments. Or do go build -x foo.go, and you'll see [...]/compile -p main [...].

Both main and command-line-arguments are reserved, but they don't belong to the standard library. Perhaps it's correct to say that they belong to ad-hoc packages, those constructed via lists of Go files alone.

I'm also a bit surprised that the two commands above give different package paths. I think that's counter-intuitive, but maybe there's a good reason for it.

[bcmills]

Import paths without dots are reserved for the standard library _and toolchain_.

command-line-arguments and main are both synthesized by the toolchain: if you try to import them from some other package you're gonna have a bad time.

[mvdan]

Thanks, I like that wording. It's clear in my mind now. I'll have a look at sending a CL before the freeze is over :)

[mvdan]

I'd like to work on this this cycle. Any thoughts on where such a piece of documentation could go? I'm thinking either go help modules or https://golang.org/ref/mod. I imagine the latter might be best, because we don't want go help modules to become too long for terminals.

[jayconrod]

https://golang.org/ref/mod would be best. Ideally go help modules will be significantly shortened in 1.16, and it refer to that, plus some introductory docs.