The Compatibility Promise

## What the document actually says Go ships a short policy document, usually called the Go 1 compatibility promise, that commits to this: a program written to the Go 1 language specification, using the documented API of the standard library, will continue to compile and run correctly, unchanged, with later Go 1.x releases. Two nouns carry the whole thing — the **language specification** and the **documented standard-library API**. Anything outside those two is not promised, and the document says so explicitly rather than leaving it to be discovered. Notice what "Go 1" means here. It is not a version you install; it is the name of the compatibility epoch. Go 1.21, Go 1.25 and Go 1.27 are all "Go 1" for this purpose. There is no planned breaking successor release: the stated strategy is to keep evolving inside Go 1 by adding, never by redefining. ## It is a promise about source, not about binaries Go has no stable ABI. Compiled packages and binaries are tied to the exact toolchain that produced them, and you cannot link an object file built by one release into a program built by another. So the promise is: take your source, install a newer toolchain, rebuild, and the program still works. An upgrade is a recompile plus a test run, not a migration project. This is the practical reason Go upgrades are cheap, and it is the point candidates most often get backwards — "my old binary keeps working" is true only in the trivial sense that a statically linked binary keeps running; it is not what the promise is about. ## Why the standard library only grows If documented API can never break, there is exactly one way to fix a standard-library design mistake: add a replacement beside it and leave the original in place. That is visible all over the tree: - `slices` and `maps` (Go 1.21) added generic helpers rather than changing anything in `sort`. - `math/rand/v2` (Go 1.22) is a new import path with a cleaner API, because `math/rand` itself could not be changed. - `encoding/json/v2` (Go 1.27) shipped alongside `encoding/json` rather than redefining it. - Old API such as `io/ioutil` still exists — now as thin wrappers over `os` and `io` — carrying a `Deprecated:` paragraph in its documentation. A `Deprecated:` marker under this policy means "no longer recommended, will not be improved". It does not mean "scheduled for removal", because removal is precisely what the promise forbids. ## What "correctly" does and does not cover The promise is about programs that were **correct** to begin with. It does not promise the same performance, the same memory footprint, the same goroutine interleaving, the same garbage-collection timing, or the same output for behaviour the specification declares unspecified. Go 1.24 replaced the map implementation with Swiss Tables and Go 1.26 turned on the Green Tea collector by default; both changed how programs behave in time and memory, and neither touched a documented API, so neither is a compatibility break. The document also lists explicit carve-outs — security fixes, fixes to bugs in the compiler, runtime or libraries, specification errors, use of `unsafe`, and the tooling around the language. Tools were never in scope at all: `gofmt`'s output has changed, `go test` runs vet checks it did not use to run, and `go tool doc` was removed in Go 1.26. ## Why this is worth understanding The promise is the reason a Go service that nobody touched for three years usually rebuilds on the current toolchain with no edits, which in turn is the reason staying current on security patches is cheap. The cost is paid by the language: Go carries its old mistakes forever, and the standard library accumulates API nobody should use any more. That is a trade the Go team made deliberately, and being able to state both sides of it — cheap upgrades, permanent cruft — is what an interviewer is listening for.