cmd/go: reserve example/ and test/ as non-stdlib path prefixes

[bcmills]

The go command automatically fetches modules from network hosts, provided that those modules have a path whose first element includes a dot character (.).

First-elements that do not include a dot are, in general, reserved for the standard library and the Go toolchain (see #32819). Some names (std, cmd, all) have a special meaning no matter where they are used. Others (such as archive and debug) are currently standard-library prefixes but not packages, but could be made so in the future (as was done in the case of encoding).

Still others currently have no meaning, but may be assigned a special meaning in the future: for example, I would like to add mod to refer to the main module independent of its path (that would be a separate proposal).

The fact that import paths are required to contain a dot occasionally causes user consternation (#37554, #34592).

I propose that we explicitly reserve the following package paths for user code:

• for general use:
  • local
    • But not localhost, which we may at some point want to treat as a hostname.
• for documentation, tutorials, and bug reports:
  • example (along the lines of example.com, because it looks more like “something you should replace” than local does)
• for tests, especially tests of tools that manipulate modules (and thus need a “clean” module to run in):
  • test, which we already sort-of use:

    go/test/bench/go1/go.mod

    Line 1 in b1a783d

    module test/bench/go1

• for module-graph and package-import-graph examples:
  • main (because it is useful to indicate "the main module", and a package main is not importable anyway), and
  • any valid module path that consists of a single letter, because we already use those a lot in cmd/go tests.

CC @bronze1man @DisposaBoy @mvdan @jayconrod @matloob @thepudds

[mvdan]

Wouldn't main fall in the same category as, or perhaps be confused with, mod?

I'm overall in favor of this proposal. I seem to recall that @rogpeppe uses 0.0.0.0 as a module name, because it's a valid hostname and it contains dots, yet it can never be used to reach anything on the internet as it's not a usable IP. However, I have to admit that I too prefer using human-readable names like example or test, and I too have been doing it in tests.

From the tooling perspective, these rules are easy to implement, so that doesn't worry me either. The rules should be well documented, though, and probably alongside #32819.

Do you reckon that any sort of API would be useful for tools here? Similar to https://golang.org/pkg/go/token/#IsKeyword, imagine something like x/mod.IsLocal(path string) bool and x/mod.IsReserved(path string) bool. Their implementations would be pretty trivial, but the big advantage is that if we ever change the rules, we could easily bring the entire ecosystem in sync.

[bcmills]

Wouldn't main fall in the same category as, or perhaps be confused with, mod?

Maybe? I'd be fine with omitting it from the reserved names.

[bcmills]

Do you reckon that any sort of API would be useful for tools here?

Maybe? I'm not sure who would use them, though: I don't think we should explicitly reject other dotless paths at this point (we can break them if/when we need the name for something else, but if users are confident we'll never use their name I see little harm in letting it persist).

I guess it could be useful for linters..?

[bcmills]

(search.IsMetaPackage is what we currently use to enumerate the actually-meaningful non-package paths, but I don't think it covers builtin which is also somewhat special.)

[dmitshur]

I'll point out a cost of implementing this change, since I don't see it mentioned here so far, is that this will increase the amount of special cases. Special cases need to be documented, taught and learned by all Go users. Users who are not aware of the special cases and run into them accidentally may be surprised.

I think it's a good idea to evaluate how often each special case is expected to be used. For example, the package name main is a special case, and it is used very often, and adds more value than cost. The package name documentation is another special case, but it is used very infrequently, and has a higher cost than value (it was kept because of backwards compatibility reasons).

[jayconrod]

What would it mean to reserve these paths? I'm guessing a documented promise to never create std packages with those prefixes?

Should we allow dotless paths using reserved prefixes in the GOPROXY protocol?

[bcmills]

What would it mean to reserve these paths? I'm guessing a documented promise to never create std packages with those prefixes?

Yep. Specifically, we would apply the Go 1 compatibility policy to the non-existence of these paths in std.

[bcmills]

Should we allow dotless paths using reserved prefixes in the GOPROXY protocol?

Not at this time. (We could consider it as a future change, but since these paths explicitly do not have a single source of truth, I don't think they'd be a good fit.)

[slrz]

  * `example` (along the lines of `example.com`, because it looks more like “something you should replace” than `local` does)

What about jusing using example.com and the other existing DNS zones (example, invalid, test) reserved for test and documentation usage? If we already rely on the DNS, why not use its existing conventions for reserved names?

[dmitshur]

@slrz What you're suggesting is already possible, it does need any work to be completed. Or are you suggesting that as a reason this proposal should not be accepted?

[bcmills]

@slrz, IANA made the dubious decision to host an actual server on https://example.com.

While I do use those domains in examples myself, I could reasonably understand someone wanting to avoid them on security grounds: if those servers are ever compromised, they could serve go-import tags that point to malicious code.