How does a `//go:build go1.21` line let one file use a newer language feature while the package still builds on older releases?

## Two mechanisms in one comment line A build constraint at the top of a Go file, `//go:build go1.21`, is doing two separable things. ### Mechanism 1: file selection The toolchain sets a **release tag** for its own version and every earlier one: a Go 1.27 install satisfies `go1.1` through `go1.27`. So: - `//go:build go1.21` — the file is part of the package on Go 1.21 and later, and invisible to anything older. - `//go:build !go1.21` — the file is part of the package only on releases older than 1.21. Because the tags are cumulative, the negated form is the correct way to write "older than 1.21". Writing `//go:build go1.20` for the fallback is the classic mistake: that tag is also satisfied by Go 1.27, so both files would compile and the package would fail with duplicate declarations. ### Mechanism 2: the language version The module's go line sets the language version for the whole module, but a `//go:build go1.x` constraint **raises** it for the single file that carries it. That is the part people miss. In a module declaring `go 1.20`, a file with `//go:build go1.21` is compiled at language version 1.21 and may therefore use the `max` builtin, which Go 1.21 introduced. Without the constraint the same file is rejected with a message telling you the language version it was compiled at and pointing at go.mod. The mechanism only raises; a constraint naming an older release does not lower a file below the module's go line. ### Putting them together The pair of files below lets a package use `max` where it is available and fall back to a hand-written comparison where it is not — while go.mod keeps saying `go 1.20`, so consumers still on Go 1.20 can build the module at all. Rules that make the pattern work: 1. Both files declare **the same package** and the same exported (or unexported) identifiers with identical signatures, so callers compile either way. 2. The constraints must be **mutually exclusive and exhaustive** — `go1.21` and `!go1.21` — or you get either a duplicate declaration or an undefined symbol. 3. `//go:build` must appear before the package clause, followed by a blank line. 4. Keep the guarded surface tiny. The bigger the divergence between the two files, the more likely one of them rots untested. ### When to reach for it, and when not to This is the tool for **optional** adoption: you want a newer feature where it exists without imposing a floor on every consumer of a widely used library. It is the polite alternative to raising the go line for people who did not ask for it. It is the wrong tool when the newer feature is not optional — if the module genuinely cannot work correctly without it, gate the whole module by raising the go line and give consumers one clear version error instead of a subtly different build. It is also a real maintenance cost: every guarded file needs the fallback to be exercised, which means running your tests on the oldest release you claim to support, not just on the newest. ### A related trap Build constraints select files and raise language versions; they cannot conjure standard-library symbols. A file guarded with `//go:build go1.24` may call an API introduced in Go 1.24 safely, because it simply is not compiled on anything older — that is precisely the guard's value. But the same call in an unguarded file compiles for you and fails with an undefined-symbol error for anyone on an older release, which is why the guard has to sit on the file, not merely in your head.