The go version line in go.mod doesn't peg the version of the actual compiler, it only pegs the version of the language. It's analogous to flags like --std=c++20 in C++ compilers. If you have code that is, for example, valid go 1.17 and also valid go 1.18, but it behaves differently somehow between the two for reasons that are considered implementation details instead of language changes (for instance, depending on behavior changes in standard libraries), the behavior you get will depend on the version of the go tool that you happen to be running when you build it, not by what's defined in go.mod. That's sort of what's changing in go 1.21 - there's now a "toolchain" directive to specify the precise compiler version that should be used, which is slightly independent of the version of the language semantics that you want to apply.

But of course, it's still not that clear - because the toolchain directive is only respected in the "main" module, and it's also still only a minimum. That means you can't actually guarantee that your module will always be built with exactly that toolchain version - if it's included in someone else's module then it will be built with whatever they happen to be running, and it can always be built with a later version no matter what.

I think the part they take issue with that might surprise you is if you decide to start using a dependency, and that dependency declares in it's go.mod file (not yours) that it needs a newer version than yours, and that triggers a download and toolchain swap.

I think it's... Iffy. I'd prefer it to fail and for it to be up to me to upgrade, personally.

I think that's only what happens for binary (tool) dependencies that are built on their own, though. For library dependencies that you're only building against, their "toolchain" directive would be ignored, because they're not the main module (https://go.dev/doc/toolchain).

OK, if I understand correctly:

I might have a git repo, and nowhere in it does anything say "go1.2x"

My go.mod might say go1.26

But one of the dependencies, in it's source (not anywhere to be found in my source), says go1. 29

So when you build my source, it will build with go1.29

If that's the case, then yes, I'm appalled, AND this article did a terrible job of informing me of the situation

Your go.mod would be considered untidy

> A module’s go line must declare a version greater than or equal to the go version declared by each of the modules listed in require statements.

Idk, I just looked at the go.mod docs (I assume go.mod is the current standard but I really can't say for certain, the go ecosystem is more of a cluster than python, imo): https://go.dev/ref/mod#go-mod-file-go

> The go directive sets the minimum version of Go required to use this module. Before Go 1.21, the directive was advisory only; now it is a mandatory requirement: Go toolchains refuse to use modules declaring newer Go versions.

Seems like a non-issue. I'm still unclear what TFA is saying

That's what GOTOOLCHAIN=local means

IIRC the go version in go.mod is a minimum go toolchain version. In the future if you pull in a dep with a higher minimum toolchain version, it would be unbuildable without upgrading your toolchain. I expect there is an env variable to disable this, though.