How do you decide whether an exported Go struct in a shared library may embed a type at all?

## What you embed, you publish - and cannot unpublish Embedding a type in an exported struct promotes its exported methods onto your type. From the moment your module is tagged, those methods are your API: importers compile against them, and there is no marker that says "this one was not really mine". The decision therefore belongs at API review, not to whoever is typing. ### The three costs, in the order they bite **1. Irreversibility.** Removing an exported method is a breaking change under Go's module rules, and a breaking change means a new major version with a new module path ending in `/v2`. That is not a line of code, it is a migration you are asking every consumer to fund and schedule. A method that arrived by accident costs exactly as much to remove as one you designed. **2. You inherit the dependency's release process.** This is the argument most teams have not thought through. Whoever owns the embedded type can add a method in an ordinary minor release, and that method silently becomes part of *your* exported surface on your next bump. Three ways that hurts: - It collides with something you already promoted from a second embedded type, and the ambiguous selector breaks importers who were calling a name that had nothing to do with the upgrade. - It changes behaviour at a distance. Gaining a `String() string` method makes your values print differently under `fmt`; gaining a `MarshalJSON` method changes what your callers put on the wire. Neither shows up as a compile error. - It widens interface satisfaction, so your type can be passed to places you never designed for and now must keep working. **3. It removes your freedom to change the collaborator.** The promoted method set is a mirror of a dependency's API. Swapping it for a different implementation with a different shape means deleting exported methods, which loops back to cost one. ### The rule that survives contact with reviewers Embed in an exported type only when **both** hold: - The embedded type's *entire* method set is deliberately part of the contract - typically because you are decorating something and want the untouched methods to pass through by design. - You own that type, in the same module, so its API cannot move under you. Otherwise: named field, plus explicit forwarding for the two or three calls that belong in your surface. The one-line test to settle an argument is *would you write and document this method by hand?* If nobody wants to stand behind `Lock` as an API commitment, `Lock` should not be on the type. ### Where the rule deliberately does not apply Inside a package, and inside an `internal/` tree, embedding is cheap. You can see every caller, and unembedding is a single atomic change with a compiler to find the fallout. Applying the exported-boundary rule everywhere is how a sensible policy gets a reputation for pedantry and stops being followed. Say explicitly that the constraint is about the module boundary. A monorepo where every consumer builds from head is a middle case: breaking changes are real work but they are *your* work, done in one commit, so the calculus tilts back towards convenience. An externally published module with unknown consumers is the strict end. ### Who pays, and how you make the argument The complaint against the rule is fair: forwarding methods are boilerplate, and boilerplate is written by the team that owns the library, repeatedly, while the benefit is spread over consumers who never notice it. The honest framing is that this is a transfer of cost from an unpredictable future to a predictable present. A forwarding method is ten seconds now; a major-version migration is quarters of other people's time, spent at whatever moment the collision happens to land. Two things make the rule stick where argument alone will not: - **Write it in the package's contributing notes**, phrased as the test rather than the prohibition, so a reviewer can point at it in one line instead of re-deriving the reasoning on every pull request. - **Make "an embedded field was added" a review trigger**, in the same bucket as adding a method to an exported interface. Both change what compiles for someone else, and neither looks like an API change in a diff. ### What you should be willing to concede If the promoted surface really is the contract - a wrapper that must behave as the thing it wraps - insist on the forwarding methods anyway and you have written a worse library, more code and more drift for no benefit. The rule is a default that a reviewer can be talked out of with a specific reason, which is what separates a policy from a lint rule.