Gating Features in go.mod

## The one line, and its two jobs Every module has a `go.mod` file, and near the top it carries a directive like: ``` module example.com/internal/telemetry go 1.22 ``` That single line does two different things, and most confusion about it comes from collapsing them into one. ### Job 1: a minimum required release The go line says "this module needs Go 1.22 or later". Since **Go 1.21** that is a hard requirement: if the release doing the build is older than the go line, the go command reports an error naming the required version instead of attempting the compile, unless it is able to run a newer Go release instead. Before Go 1.21 the line was advisory — the toolchain compiled anyway and only mentioned the module's go version as a note appended to whatever compile error you got, which produced very confusing bug reports ("undefined: something" plus a version hint at the bottom). It is a **floor**, not a pin. Nothing stops a newer release from building the module; the whole point is that a Go 1.27 install can build modules whose go lines say 1.16, 1.21 or 1.25. ### Job 2: the language version The go line also sets the **language version** used to compile every file in the module. Language changes in Go are gated on it, so a module with a low go line does not silently pick up new syntax and semantics when someone builds it with a newer compiler. Concretely: - `min`, `max` and `clear` builtins arrived in **Go 1.21**; - per-iteration loop variables and `for range` over an integer arrived in **Go 1.22**; - range-over-function iterators arrived in **Go 1.23**; - generic type aliases arrived in **Go 1.24**. A module whose go.mod says `go 1.20` gets none of those, no matter how new the installed compiler is. Reach for one and the compiler rejects it with a message that names the language version it was given and points you back at go.mod. This is what makes the go line a *feature gate*. It exists so that upgrading your compiler is a safe, boring operation: the language your existing code is compiled as does not move until you move it. ### What the go line is not - **Not the compiler version you installed.** Those are independent; the installed release just has to be at least as new. - **Not a version of your dependencies.** Each dependency records its own go line and is compiled at its own language version. - **Not necessarily a per-file setting.** It applies module-wide, although a `//go:build go1.x` constraint can raise the language version for a single file. ### A standard-library subtlety worth knowing The go line gates *language* features. Standard-library **symbols** come from whatever release compiles the code, so a `go 1.20` module that calls a function introduced in Go 1.24 will compile happily on a Go 1.24 install and fail with a plain "undefined" error for anyone on Go 1.22 — a much worse error than a version requirement. Since **Go 1.27** `go test` runs the `stdversion` vet check by default, which reports uses of standard-library symbols that are too new for the module's effective Go version, turning that trap into a clear diagnostic. When you start depending on new stdlib APIs, raise the go line so consumers get an honest version error instead. ### Changing it `go mod edit -go=1.24` rewrites just the directive. `go mod tidy -go=1.24` sets it and reconciles the module's requirements to what that version implies. Either way, raising it is a decision with other people attached: every consumer of your module inherits the floor.