Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
cmd/go: go directive is insufficiently documented for module authors to be able to make a decision about its value #30791
Go 1.12 has added a
Additionally, a relevant paragraph from https://golang.org/doc/go1.12#compiler:
There is additional information available in issues, proposals, commit messages and code review comments, which I did not mention above. However, that information is not readily accessible to users.
It is very common for package authors to aim to ensure their Go packages can be used in multiple versions of Go. Sometimes it's just Go 1.12.x and Go 1.11.x (the current and previous releases). Other times the goal is to support even older versions of Go. This often includes running tests in CI with those versions of Go to ensure that the build and tests are successful. When these package authors add a go.mod file file to their repositories, they should be able to make a sensible decision about what
I believe the current documentation is not sufficient for module authors to make a well-informed decision on whether to include the
I think we should try to improve documentation to resolve that. But first I want to make sure others agree that it's a problem.
(This is based on looking over the discussions that have happened around various PRs/CLs where the
I'm sure we should write better docs.
The basic guideline is fairly simple: a "go" directive 1.N means that the code in that module is permitted to use language features that existed in 1.N even if those features were removed in later releases of the language.
In other words, if the code compiles successfully at version 1.N, then it will continue to compile for all later versions of the language, even if it happens to use language features that were later removed.
To a first approximation, nobody should ever have to worry about the "go" directive. The only likely time you might need to set it manually is if you are copying some existing code to a new module, that code uses some obsolete language feature, and you don't have time to rewrite it. In that case you might want to set the "go" directive (using
referenced this issue
Mar 12, 2019
My understanding of #28221 is that it should not only permit the older features, but also prohibit newer features. Otherwise, there is little incentive for folks to upgrade to a language version beyond the removed features: they can just set
That understanding is based on this part of the proposal discussion:
That has an interesting interaction with build tags, though: if I set
I would argue that a
Or perhaps it should result in an explicit error, since the user may otherwise be confused that it has no effect.
Those are good questions. When looking for an answer, we should make sure that authors who wish to create Go modules that work with a wide range of Go versions (e.g., 1.8–1.12 as
I made similar conclusions based on that type alias example. When I asked Ian about it, his response was:
Which made me understand that the type alias example can be misleading when thinking about how the