In Go, what breaks when you add a method to an interface your package already exports?

## The mechanic An interface names a set of methods. A type satisfies it when its method set contains all of them, and the compiler verifies that at each point of use: an assignment, an argument, a return, a channel send. Add a method to the interface and the required set grows. Any type that does not have the new method no longer satisfies the interface, and every place that used it as that interface stops compiling. The type itself still compiles -- nothing about the struct changed. The failure appears at the boundary, which means it appears in the *consumer's* build, often in another repository, at whatever moment they next upgrade your module. ## Why Go offers no softening Some languages let an interface carry a method with a body, so widening the interface supplies an implementation to every existing implementer. Go has nothing equivalent. An interface declares signatures only; there is no default, no optional member, and no way to mark a method as "implement it if you like". Embedding does not help either -- `type StoreV2 interface { Store; Refund(...) }` is a new, wider interface, and any function that takes `StoreV2` has the same requirement. The contrast with a struct is the point worth carrying into design discussions. Adding an exported method to a struct is backward compatible: existing callers keep working and simply gain a capability. Adding a method to an exported interface is backward incompatible for anyone implementing it. So the decision to export an interface, rather than a concrete type, is a decision about which changes you may safely make later. ## The options when you must add the capability **Declare a second, narrow interface and assert for it.** Leave the published interface untouched, put the new method in an interface of its own, and at the call site ask whether the value also satisfies it: ```go if r, ok := s.(Refunder); ok { return r.Refund(ctx, authID) } return errors.ErrUnsupported ``` Every existing implementer keeps compiling and simply does not get the fast path or the extra behaviour. This is exactly how the standard library grows capabilities: `io.Copy` uses `io.WriterTo` or `io.ReaderFrom` when its arguments happen to provide them and otherwise falls back to a plain read-write loop, and an HTTP handler asks whether its `http.ResponseWriter` also satisfies `http.Flusher` before flushing. The cost is that the capability is now optional, so the caller needs a defined behaviour when it is absent -- a fallback, or a clear error such as `errors.ErrUnsupported`. **Publish a new, wider interface beside the old one** and migrate consumers deliberately. Honest, but it doubles the vocabulary and every consumer must eventually choose. **Change all the implementers.** Only available when you can see them all -- a single repository, or a module nobody outside your organisation depends on. Inside one repo this is often simply the right answer: change the interface, change the implementations, one commit. **Take the interface out of the exported surface.** If the interface existed only because the package wanted to hand back an abstraction it did not need, the real fix is to return the concrete type and let each consumer declare the narrow interface it uses. A consumer-declared interface can be widened freely, because the only package that must satisfy it is the one that also uses it, and both sides are in the same build. ## The design lesson The rule that follows is not "never export an interface" -- `sort.Interface` and `io.Writer` are exported interfaces others implement, and they are stable precisely because they were designed to be small and final. The rule is that an exported interface is a promise you cannot widen. If you cannot say who implements it besides you, and you cannot say that its method set is finished, do not export it.