Go explains how package authors can automate API migrations

The Go project published a detailed explanation of its source-level inliner on March 10, showing how library maintainers can encode API migrations for consumers. The engineering article describes the //go:fix inline directive used by the revamped go fix command in Go 1.26.

A migration travels with the wrapper

A maintainer can implement an old function using its replacement and annotate the wrapper for inlining. The tool then rewrites callers using that implementation. The article also describes migrations for aliases and constants, and explains why argument evaluation and side effects complicate the transformation.

This is useful for API stewardship because a deprecation notice usually leaves every consumer to translate intent into code. An executable migration can make the intended replacement visible in an ordinary diff. It also creates a concrete artifact that a package maintainer can review alongside the compatibility wrapper.

Treat the resulting diff as source

Unlike a compiler optimization, this inliner permanently changes the program text. Go’s explanation emphasizes conservative handling of behavior, which can leave intermediate variables that deserve manual cleanup.

A sensible adoption experiment is one small deprecated API with representative callers: literals, nested calls, and expressions with observable effects. Inspect whether the generated code communicates the new API well, then run the package’s existing behavioral checks. Those checks answer a different question from whether the rewrite was mechanically valid.

Maintainers should keep the compatibility wrapper understandable after adding the directive. Future readers still need to see why the old entry point maps to the new one, particularly when argument order or defaults differ. The migration is part of the API’s maintenance story.