go and toolchain directives

Canonical guidance

• keep go honest about the minimum version the module needs
• use toolchain only when the default developer toolchain should be newer
• review both directives when adopting new language or library features

Use when

• upgrading Go versions
• enabling new language features
• standardizing local toolchains across contributors

Avoid

• bumping go casually without using the new requirement
• using toolchain to paper over incorrect version requirements
• forgetting that older consumers read the go directive as compatibility signal

Preferred pattern

module example.com/app

go 1.23
toolchain go1.25.3

Anti-pattern

• setting go to the newest company toolchain even though the module only needs an older language baseline

Explanation: This anti-pattern is tempting because standardization feels neat, but it raises the compatibility floor without a real reason.

Why

• these directives communicate compatibility and toolchain expectations to both humans and tooling