nixpkgs/pkgs/build-support/go

Go toolchain/builder upgrade policy

Go promises that "programs written to the Go 1 specification will continue to compile and run correctly, unchanged, over the lifetime of that specification" 1. Newer toolchain versions should build projects developed against older toolchains without problems.

Definition(a "toolchain-breaking" package): There are however Go packages depending on internal APIs of the toolchain/runtime/stdlib that are not covered by the Go compatibility promise. These packages may break on toolchain minor version upgrades.

Definition(a "toolchain-latest" package): Packages providing development support for the Go language (like gopls, golangci-lint,...) depend on the toolchain in another way: they must be compiled at least with the version they should be used for. If gopls is compiled for Go 1.23, it won't work for projects that require Go 1.24.

Go only ever has two supported toolchains. With a new minor release, the second last Go toolchain is automatically end of life, meaning it won't receive security updates anymore.

Based on this, we align on the following policy for toolchain/builder upgrades:

1. Default toolchain (the go package) and builder (buildGoModule) are upgraded to the latest minor release of Go as soon as it is released. As it is a mass rebuild, this package will be made against the staging branch.

2. The go_latest toolchain and the buildGoLatestModule are also bumped directly after release, but the update goes to the master branch.

   Packages in toolchain-latest SHOULD use go_latest/buildGoLatestModule. Packages in nixpkgs MUST only use this toolchain/builder if they have a good reason to do so A comment MUST be added explaining why this is the case for a certain package. It is important to keep the number of packages using this builder within nixpkgs low, so the bump won't cause a mass rebuild.

   go_latest MUST not point to release candidates of Go.

   Consumer outside of nixpkgs on the other hand MAY rely on this toolchain/builder if they prefer being upgraded earlier to the newest toolchain minor version.

3. Packages in toolchain-breaking SHOULD pin a toolchain version by using a builder with a fixed Go version (buildGo1xxModule). The use of buildGo1xxModule MUST be accompanied with a comment explaining why this has a dependency on a specific Go version. The comment should target the Go team in nixpkgs and ease their work in case they have to touch the package (see 5.).

4. The builder SHOULD be directly used as package input, not by overriding buildGoModule in all-packages.nix, to make this dependency explicit.

5. Go toolchains MUST be removed soon after they reach end of life, latest with the next security update that won't target them anymore.

   When an end-of-life toolchain is removed, builders that pin the EOL version (according to 3.) will automatically be bumped to the then oldest pinned builder (e.g. Go 1.22 is EOL, buildGo122Module is bumped to buildGo123Module).

   If the package won't build with anymore with that builder, the package is marked broken. It is the package maintainers responsibility to fix the package and get it working with a supported Go toolchain.