Which mechanisms let a Go module ship its own GODEBUG defaults instead of relying on the environment?

## Why declare settings instead of exporting a variable Setting `GODEBUG` in a deployment manifest works, but it has a nasty property: the behaviour of the program now depends on something that is not in the repository. Local runs, `go test`, CI and production disagree, and the one place a reviewer looks — the diff — says nothing. Go therefore lets a module carry its own defaults, compiled into the binary. ## The go.mod godebug directive Since Go 1.23, `go.mod` (and `go.work`) accepts `godebug` lines: ``` module example.com/billing go 1.24 godebug ( default=go1.23 panicnil=1 ) ``` A single setting can also be written on one line: `godebug panicnil=1`. Two forms matter. `godebug name=value` pins one named setting. `godebug default=go1.N` moves *every* compatibility default to what Go 1.N did — a blunt instrument, useful when you are stepping a language version forward and want to separate "compile against the newer toolchain" from "adopt all its behaviour changes", and dangerous as a permanent posture because it hides which single behaviour you actually depend on. These lines take effect when main packages in that module are built. A `godebug` line in a *dependency's* `go.mod` does not reach into your program: it is the main module that decides. ## The //go:debug directive Since Go 1.21 a directive comment can set a default for one binary: ```go // Command billing-worker settles invoices. // //go:debug panicnil=1 package main ``` The rules to remember: it must be in the comment block immediately preceding the `package` clause, and it is only permitted in a main package or in a test file. That restriction is deliberate — a library has no business dictating run-time behaviour for the programs that import it, so the directive is confined to the artefacts that actually become a binary or a test binary. Putting one in an ordinary library package is a build error rather than a silent no-op. ## The baseline underneath both Underneath these declarations there is a baseline: the compatibility defaults a build starts from track the language version the main module declares, so that upgrading the toolchain without changing that line does not silently adopt every new behaviour at once. The mechanics of that language-version line itself are a separate topic; what matters here is that it is the bottom of the stack, and both `godebug` and `//go:debug` sit above it as explicit overrides. ## Precedence, from weakest to strongest 1. Defaults implied by the main module's declared language version. 2. `godebug` lines in the main module's `go.mod` (or `go.work`). 3. `//go:debug` directives in the main package or test file being built. 4. The `GODEBUG` environment variable at run time. The environment variable winning is the important end of that list. Whatever a module bakes in, an operator can still override it on a running deployment — which is what makes GODEBUG usable during an incident, and also means a compiled-in setting is a default, never a guarantee. ## Which one to use Use the `go.mod` `godebug` line when the whole module needs the setting — several commands built from one repository, and you want the tests to see it too. Use `//go:debug` when only one command needs it, or when the setting belongs to a test binary while production code stays on the new behaviour. Use the environment variable for experiments and for incident response, then promote the result into the repository so the next person can see it. Reserve `default=go1.N` for a deliberate, time-boxed step of the language version, and prefer a single named setting whenever you know which behaviour you are actually depending on. ## What this buys you A declared setting is testable. `go test` builds the test binary with the module's `godebug` lines applied, so a test can pin the behaviour you depend on and fail loudly the day someone removes the declaration. An environment-only setting has no such property: the test suite runs on the new behaviour and passes, and production runs on the old one.