docs/release-notes: document go_latest, buildGoLatestModule, Go upgrade policy (#395462)

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 `<pkg>.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.

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"
   ],

doc/release-notes/rl-2505.section.md

@@ -230,6 +230,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`

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.