From dff25816ade78bab25d992759980198933fca2cc Mon Sep 17 00:00:00 2001 From: Paul Meyer Date: Wed, 2 Apr 2025 13:32:49 +0200 Subject: [PATCH 1/3] go/policy: some clarification Signed-off-by: Paul Meyer --- pkgs/build-support/go/README.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/pkgs/build-support/go/README.md b/pkgs/build-support/go/README.md index 89f0f83f019d..9a0b59836921 100644 --- a/pkgs/build-support/go/README.md +++ b/pkgs/build-support/go/README.md @@ -3,14 +3,13 @@ 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 updates. -We name packages that (often) break on toolchain updates `toolchain-breaking`. +These packages may break on toolchain minor version upgrades. -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. +**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. -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. @@ -26,7 +25,9 @@ Based on this, we align on the following policy for toolchain/builder upgrades: 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. + `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. From ad579ea83d5c7056f584d44e8451e9b9150bd79f Mon Sep 17 00:00:00 2001 From: Paul Meyer Date: Wed, 2 Apr 2025 14:00:52 +0200 Subject: [PATCH 2/3] docs/go: add section about versioned toolchains/builders Signed-off-by: Paul Meyer --- doc/languages-frameworks/go.section.md | 15 +++++++++++++++ doc/redirects.json | 3 +++ 2 files changed, 18 insertions(+) diff --git a/doc/languages-frameworks/go.section.md b/doc/languages-frameworks/go.section.md index 172bf2ca8f37..fcc3c687d354 100644 --- a/doc/languages-frameworks/go.section.md +++ b/doc/languages-frameworks/go.section.md @@ -195,6 +195,21 @@ Specifies the contents of the `go.sum` file and triggers rebuilds when it change Defaults to `null` +## Versioned toolchains and builders {#ssec-go-toolchain-versions} + +Beside `buildGoModule`, there are also versioned builders available that pin a specific Go version, like `buildGo124Module` for Go 1.24. +Similar, versioned toolchains are available, like `go_1_24` for Go 1.24. +Both builder and toolchain of a certain version will be removed as soon as the Go version reaches end of life. + +As toolchain updates in nixpkgs cause mass rebuilds and must go through the staging cycle, it can take a while until a new Go minor version is available to consumers of nixpkgs. +If you want quicker access to the latest minor, use `go_latest` toolchain and `buildGoLatestModule` builder. +To learn more about the Go maintenance and upgrade procedure in nixpkgs, check out the [Go toolchain/builder upgrade policy](https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/go/README.md#go-toolchainbuilder-upgrade-policy). + +::: {.warning} +The use of `go_latest` and `buildGoLatestModule` is restricted within nixpkgs. +The [Go toolchain/builder upgrade policy](https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/go/README.md#go-toolchainbuilder-upgrade-policy) must be followed. +::: + ## Overriding `goModules` {#buildGoModule-goModules-override} Overriding `.goModules` by calling `goModules.overrideAttrs` is unsupported. Still, it is possible to override the `vendorHash` (`goModules`'s `outputHash`) and the `pre`/`post` hooks for both the build and patch phases of the primary and `goModules` derivation. diff --git a/doc/redirects.json b/doc/redirects.json index 570c71ea705c..4475752b367a 100644 --- a/doc/redirects.json +++ b/doc/redirects.json @@ -3006,6 +3006,9 @@ "ex-buildGoModule": [ "index.html#ex-buildGoModule" ], + "ssec-go-toolchain-versions" : [ + "index.html#ssec-go-toolchain-versions" + ], "buildGoModule-goModules-override": [ "index.html#buildGoModule-goModules-override" ], From cec2770da61a9ce227949eca34731718cb75a2ad Mon Sep 17 00:00:00 2001 From: Paul Meyer Date: Wed, 2 Apr 2025 14:13:36 +0200 Subject: [PATCH 3/3] release-notes: mention new Go upgrade policy documentation, go_latest and buildGoLatestModule Signed-off-by: Paul Meyer --- doc/release-notes/rl-2505.section.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/release-notes/rl-2505.section.md b/doc/release-notes/rl-2505.section.md index 8a395089426d..aa30b1f21208 100644 --- a/doc/release-notes/rl-2505.section.md +++ b/doc/release-notes/rl-2505.section.md @@ -226,6 +226,11 @@ - `buildGoModule` now supports a `goSum` attribute (`null` by default) to optionally provide a path to `go.sum` and correctly enabling rebuilds when the file changes. +- The newly added aliases `go_latest` and `buildGoLatestModule` are now available and can be use to prevent packages like `gopls` from breaking whenever the default toolchain minor version is lagging behind. + It can also be used _outside of nixpkgs_ to get fast access to new Go minor versions without having to wait for a staging cycle that will update the default builder/toolchain. + +- A [policy documenting the details of Go toolchain and builder upgrades](https://github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/go/README.md#go-toolchainbuilder-upgrade-policy) in nixpkgs, as well as rules related to using non-default builders like `buildGo1xxModule` and `buildGoLatestModule` has been added in-tree. + - top-level `playwright` now refers to the github Microsoft/playwright package instead of the python tester launcher. You can still refer to the python launcher via `python3Packages.toPythonApplication python3Packages.playwright`