Author(s): Jay Conrod based on discussion with Daniel MartÃ, Paul Jolly, Roger Peppe, Bryan Mills, and others.
Last updated: 2021-05-12
Discussion at https://golang.org/issue/46136.
With this proposal, go vet (and go test) would report an error if a package imports a standard library package or references an exported standard library definition that was introduced in a higher version of Go than the version declared in the containing module's go.mod file.
This makes the meaning of the go directive clearer and more consistent. As part of this proposal, we‘ll clarify the reference documentation and make a recommendation to module authors about how the go directive should be set. Specifically, the go directive should indicate the minimum version of Go that a module supports. Authors should set their go version to the minimum version of Go they’re willing to support. Clients may or may not see errors when using a lower version of Go, for example, when importing a module package that imports a new standard library package or uses a new language feature.
The go directive was introduced in Go 1.12, shortly after modules were introduced in Go 1.11.
At the time, there were several proposed language changes that seemed like they might be backward incompatible (collectively, “Go 2”). To avoid an incompatible split (like Python 2 and 3), we needed a way to declare the language version used by a set of packages so that Go 1 and Go 2 packages could be mixed together in the same build, compiled with different syntax and semantics.
We haven't yet made incompatible changes to the language, but we have made some small compatible changes (binary literals added in 1.13). If a developer using Go 1.12 or older attempts to build a package with a binary literal (or any other unknown syntax), and the module containing the package declares Go 1.13 or higher, the compiler reports an error explaining the problem. The developer also sees an error in their own package if their go.mod file declares go 1.12 or lower.
In addition to language changes, the go directive has been used to opt in to new, potentially incompatible module behavior. In Go 1.14, the go version was used to enable automatic vendoring. In 1.17, the go version will control lazy module loading.
One major complication is that access to standard library packages and features has not been consistently limited. For example, a module author might use errors.Is (added in 1.13) or io/fs (added in 1.16) while believing their module is compatible with a lower version of Go. The author shouldn‘t be expected to know this history, but they can’t easily determine the lowest version of Go their module is compatible with.
This complication has made the meaning of the go directive very murky.
We propose adding a new go vet analysis to report errors in packages that reference standard library packages and definitions that aren‘t available in the version of Go declared in the containing module’s go.mod file. The analysis will cover imports, references to exported top-level definitions (functions, constants, etc.), and references to other exported symbols (fields, methods).
The analysis should evaluate build constraints in source files (// +build and //go:build comments) as if the go version in the containing module's go.mod were the actual version of Go used to compile the package. The analysis should not consider imports and references in files that would only be built for higher versions of Go.
This analysis should have no false positives, so it may be enabled by default in go test.
Note that both go vet and go test report findings for packages named on the command line, but not their dependencies. go vet all may be used to check packages in the main module and everything needed to build them.
The analysis would not report findings for standard library packages.
The analysis would not be enabled in GOPATH mode.
For the purpose of this proposal, modules lacking a go directive (including projects without a go.mod file) are assumed to declare Go 1.16.
When writing this proposal, we also considered restrictions in the go command and in the compiler.
The go command parses imports and applies build constraints, so it can report an error if a package in the standard library should not be imported. However, this may break currently non-compliant builds in a way that module authors can‘t easily fix: the error may be in one of their dependencies. We could disable errors in packages outside the main module, but we still can’t easily re-evaluate build constraints for a lower release version of Go. The go command doesn‘t type check packages, so it can’t easily detect references to new definitions in standard library packages.
The compiler does perform type checking, but it does not evaluate build constraints. The go command provides the compiler with a list of files to compile, so the compiler doesn't even know about files excluded by build constraints.
For these reasons, a vet analysis seems like a better, consistent way to find these problems.
The analysis in this proposal may introduce new errors in go vet and go test for packages that reference parts of the standard library that aren't available in the declared go version. Module authors can fix these errors by increasing the go version, changing usage (for example, using a polyfill), or guarding usage with build constraints.
Errors should only be reported in packages named on the command line. Developers should not see errors in packages outside their control unless they test with go test all or something similar. For those tests, authors may use -vet=off or a narrower set of analyses.
We may want to add this analysis to go vet without immediately enabling it by default in go test. While it should be safe to enable in go test (no false positives), we‘ll need to verify this is actually the case, and we’ll need to understand how common these errors will be.
This proposal is targeted for Go 1.18. Ideally, it should be implemented at the same time or before generics, since there will be a lot of language and library changes around that time.
The Go distribution includes files in the api/ directory that track when packages and definitions were added to the standard library. These are used to guard against unintended changes. They're also used in pkgsite documentation. These files are the source of truth for this proposal. cmd/vet will access these files from GOROOT.
The analysis can determine the go version for each package by walking up the file tree and reading the go.mod file for the containing module. If the package is in the module cache, the analysis will use the .mod file for the module version. This file is generated by the go command if no go.mod file was present in the original tree.
Each analysis receives a set of parsed and type checked files from cmd/vet. If the proposed analysis detects that one or more source files (including ignored files) contain build constraints with release tags (like go1.18), the analysis will parse and type check the package again, applying a corrected set of release tags. The analysis can then look for inappropriate imports and references.