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

proposal: cmd/vet: check references to standard library packages inconsistent with go.mod go version #46136

jayconrod opened this issue May 12, 2021 · 10 comments


Copy link

jayconrod commented May 12, 2021

Author(s): Jay Conrod based on discussion with Daniel Martí, Paul Jolly, Roger
Peppe, Bryan Mills, and others.

Last updated: 2021-05-12


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

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,

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

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.

@jayconrod jayconrod added this to the Go1.18 milestone May 12, 2021
@ianlancetaylor ianlancetaylor added this to Incoming in Proposals (old) May 12, 2021
Copy link

myitcv commented May 24, 2021

@jayconrod thanks very much for writing this up, and apologies for being slow at reading it through.

I'm a little confused regarding the following conclusion:

Specifically, the go directive should indicate the minimum version of Go that a module supports.

AFAIU, one of the roles of the go directive is to enable features like go:embed:

-- blah.txt --
-- go.mod --

go 1.15
-- hello.txt --
-- main.go --
package main

import (
        _ "embed"

//go:embed blah.txt
var s string

func main() {
        fmt.Printf("%v\n", s)

Gives (using tip):

> go version
go version devel go1.17-5e191f8f48 Tue May 18 02:39:04 2021 +0000 linux/amd64

> go run main.go
# command-line-arguments
./main.go:8:3: go:embed requires go1.16 or later (-lang was set to go1.15; check go.mod)

That is, my module needs to set go 1.16 to enable go:embed. Whether my module supports go1.15 is a function of whether my use of go1.16 features is build constrained or not, provides alternatives etc (something that is more concretely ensured by running go test using go1.15). So it's entirely possible for my module to set go 1.16 but still fully support go1.15. Therefore, as it stands today, the go directive is enabling later features rather than giving any sort of accurate indication on the minimum version of Go supported.

This also means that modules are not forced to bump their go directive version periodically for no real reason. If a module does not require later features, the go directive version presumably does not need to change. Because if someone has a problem with my ancient module that declares go 1.13, I'm really not going to provide support unless it's a problem they are having with the latest two Go versions (my policy in any case) - and I don't want to periodically release new versions of my module just to indicate that.

Another conclusion were the go directive to become an indicator of "minimum version of Go supported" is that modules cannot use later features, like go:embed, until the version that introduces such a feature becomes the minimum.

My understanding regarding this proposal is that it only sought to introduce a new vet rule, a vet rule that would help answer the question "do I need to bump the go directive version in order to use new feature X?" where X could be go:embed, a new standard library package, .... Because the answer would then always be "yes". However, I'm unclear therefore that the conclusion I quoted is, without changing the behaviour of the go directive, accurate.

Unless I missed the point, and instead this proposal is looking to change the advice regarding the go directive to "don't use features in newer Go versions if you want to support old Go versions". That would certainly be a valid position, but I don't think it's one that can be enforced, nor does it seem necessary given that people can use new features and support old versions via build constraints.

My feeling is that the Go version policy for a module is something sufficiently nuanced as to require specific CI testing of those versions, as well as human commentary, and not something we should try and communicate via the go directive.

But as I said, I'm late at replying to this and so might well be missing context 😄 In which case I would very much appreciate your thoughts on where my thinking has gone off the rails!


Critical edit: s/sort/sought/ 😄 - thanks @rogpeppe. My grasp of the English language is frighteningly poor.

Copy link

rogpeppe commented May 24, 2021

That is, my module needs to set go 1.16 to enable go:embed.

Thinking about this behaviour now in the context of this proposal, I think that this behaviour should be changed. In particular, I think that if the go.mod file declares go 1.14, but a build constraint on a file declares go 1.16, then go:embed (and potentially other new language/toolchain features such as generics) should be enabled.

For example, I think this example should run OK:

go run .
-- blah.txt --
-- go.mod --

go 1.15
-- hello.txt --
-- main.go --
package main

import "fmt"

func main() {
-- embed_pre1.16.go --
//+build !go1.16

package main

var s string

-- embed.go --
//+build go1.16

package main
import _ "embed"

//go:embed blah.txt
var s string

Currently it produces the error:

./embed.go:6:3: go:embed requires go1.16 or later (-lang was set to go1.15; check go.mod)

Then, as has always been the case, you can support older versions while using new features in Go versions that provide them and, as this proposal suggests, the go.mod version is the minimum supported.

I'd also suggest that non-stdlib changes such as embed or generics should be checked by the compiler rather than vet - the main reason that this current proposal is for vet is to avoid breaking existing code, and that's not a problem with new changes, or for embed that already has a check that's stricter than necessary.

Copy link
Contributor Author

jayconrod commented May 24, 2021

@myitcv @rogpeppe You both bring up some excellent questions. I'll take some more time to think and read through the go:embed history before suggesting anything though.

One thought that occurs to me: in Android, there's a separate concept of minimum and target SDK versions. The minimum version is the lowest version of Android an app works with. The target version is the version an app was compiled against. An app may use APIs from the target version that aren't in the minimum version, but it must do so conditionally.

Because of release tags in build constraints, we have a similar split here, but we haven't acknowledged or defined it. The go directive in go.mod effectively sets the target version, but the compiler treats -lang as a minimum version. The actual minimum version is only implied by build constraints.

Copy link

myitcv commented May 24, 2021

... the go.mod version is the minimum supported.

In further discussions offline with @rogpeppe and @mvdan we concluded the phrase "the minimum version of Go supported" is ambiguous at best, because the word "support" has connotations as far as users of a module are concerned. So I think we need to be careful with the wording, because "minimum" is not meant to signal anything about good support to end users.

I think we therefore also concluded that it should be documented as best practice that module authors declare a policy for Go version support separately from the go directive version. In that context, @mvdan also raised the question of whether a new module version is required when support for a Go version is dropped: @mvdan suggested a minor version bump would be appropriate in such cases (all else equal).

Copy link

bcmills commented May 27, 2021

Lately I've tended to think of the go version in the go.mod file as “the minimum Go version which supports full-fidelity builds”. Lower versions may work, but may be missing something — such as functionality (or test coverage) guarded by a go:build constraint, or reproducibility due to some change in module semantics or cmd/go behavior.

Copy link
Contributor Author

jayconrod commented May 27, 2021

I wonder if we want some machine-readable way to distinguish the minimum and target Go versions though? It would be useful for this proposal. It could be displayed by pkgsite and any other generated documentation. It would also reduce the need for the go mod tidy -compat flag in Go 1.17.

Copy link

bcmills commented Aug 12, 2021

As a real-world example, in a user was confused about build errors stemming from references to embed and io/fs in their project. I don't know for certain, but I suspect that they would have gotten a clearer failure mode if original author of those package imports had gotten a vet warning indicating that the embed and io/fs packages needed a different Go version.

Copy link

dmitshur commented Nov 10, 2021

This proposal was targeting Go 1.18, but it is still in Incoming column, and there's no assignee, so it doesn't seem that it can make it to 1.18 given the release timing. I'll move this to Proposal milestone (according to, proposals are moved to a release milestone after being accepted). Please feel free to undo if needed.

@dmitshur dmitshur modified the milestones: Go1.18, Proposal Nov 10, 2021
Copy link

soypat commented Nov 29, 2021

I'll voice my support for this proposal and share an issue that seems to be covered by the proposal:
I was working on a module with go 1.16 version and was able to add reflect.VisibleFields (added go 1.17) function to my code without being warned the module would be broken. I pushed to code to production and only realized my module was broken when a colleague opened the project with his local go 1.16 installation.

Copy link

findleyr commented Jan 19, 2022

Thanks @bcmills for pointing me here from #50689.

Gopls will need the analyzer described here in any case, as we want to better support using gopls built with a recent Go to develop for older versions of Go. In #50689, I mention that we'd probably need explicit configuration for gopls, precisely because we want to be consistent with the go command by default.

If this proposal were accepted, then gopls could simply read the go.mod go version and do the right thing for our users, without requiring external configuration.

Of course, if we implement this for gopls (initially in x/tools/internal/lsp/analysis), then it would be trivial to expose for vet by moving the analyzer to x/tools/go/analysis/passes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Status: Incoming

No branches or pull requests

8 participants