From 3ab4d2791dc01a9439cb89e264b2775b84537ab5 Mon Sep 17 00:00:00 2001 From: Paul Meyer Date: Wed, 19 Feb 2025 18:36:27 +0100 Subject: [PATCH 1/2] go: write down toolchain/builder upgrade policy Signed-off-by: Paul Meyer --- pkgs/build-support/go/README.md | 44 +++++++++++++++++++++++++++++++++ 1 file changed, 44 insertions(+) create mode 100644 pkgs/build-support/go/README.md diff --git a/pkgs/build-support/go/README.md b/pkgs/build-support/go/README.md new file mode 100644 index 000000000000..89f0f83f019d --- /dev/null +++ b/pkgs/build-support/go/README.md @@ -0,0 +1,44 @@ +## 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. + +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 updates. +We name packages that (often) break on toolchain updates `toolchain-breaking`. + +There is another set of packages that depends on the toolchain, but in another way: +Packages providing development support for the Go language (like `gopls`, `golangci-lint`,...) must be compiled 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. +We name packages that must be built with the latest toolchain to work as expected `toolchain-latest`. + +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. + + Consumer outside of nixpkgs on the other hand MAY rely on this toolchain/builder if they prefer being upgraded earlier to the newest toolchain. + +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. + +[1]: http://go.dev/doc/go1compat From da927dda898f642a56ab93f61e60de4a3772a6ce Mon Sep 17 00:00:00 2001 From: Paul Meyer Date: Fri, 28 Mar 2025 14:05:53 +0100 Subject: [PATCH 2/2] go: introduce go_latest/buildGoModuleLatest Signed-off-by: Paul Meyer --- pkgs/top-level/all-packages.nix | 3 +++ 1 file changed, 3 insertions(+) diff --git a/pkgs/top-level/all-packages.nix b/pkgs/top-level/all-packages.nix index 34f7ba025499..0444b25c212e 100644 --- a/pkgs/top-level/all-packages.nix +++ b/pkgs/top-level/all-packages.nix @@ -11665,6 +11665,9 @@ with pkgs; go = go_1_24; buildGoModule = buildGo124Module; + go_latest = go_1_24; + buildGoLatestModule = buildGo124Module; + go_1_23 = callPackage ../development/compilers/go/1.23.nix { }; buildGo123Module = callPackage ../build-support/go/module.nix { go = buildPackages.go_1_23;