You maintain a Go client SDK dozens of teams pin, and a design flaw needs a breaking change. How do you decide what ships?

## Frame the decision as somebody else's budget The question is never "what is the right API". It is "who pays, and for what benefit". Dozens of internal teams pinning your SDK means a break costs dozens of unplanned migrations, each landing in a sprint somebody else already committed. Your improved design is a benefit to you and to future readers; the migration is a cost to people who did not ask for it. Any argument that skips that asymmetry is not a maintainer's argument. So the first thing to establish is the *size* of both sides: how many importers, how deep the usage (one call site or a type implementing your interface everywhere), and how bad the flaw actually is for them today. ## The ladder, cheapest first **1. Additive, in place.** Most "we must break this" turns out not to. A new method goes on a *new* interface, detected by type assertion. A new parameter becomes a variadic option, so the constructor signature never changes again. A misnamed function gets a correctly named twin, with the old one delegating to it. The old symbol stays, marked `// Deprecated:` with the replacement named and the removal release stated. Nothing downstream stops compiling; the surface grows. **2. Parallel surface in the same major version.** When the shape is wrong rather than the name — the whole client type is unsalvageable — a second package or a second type beside the old one lets both compile at once. Consumers migrate on their own schedule; you carry two implementations for a stated window, ideally with the old one built on the new one so behaviour cannot diverge. The cost is real: two sets of docs, two sets of examples, and a support surface where people ask which to use. **3. A new major version.** This is a maintenance fork. You will backport fixes to the old line for as long as anyone is on it, and you will discover that "anyone" includes a service nobody staffs. Take it when the flaw is pervasive and the additive path would leave the API permanently confusing — and only when the organisation has actually agreed to fund the migration and the double maintenance, not when you have merely convinced yourself the new design is better. ## What justifies a break A short list, and I hold it strictly: - **Silent incorrectness.** Callers get wrong answers, lose data, or skip an authorization check without any error being returned. This is the strongest case, because the status quo already costs them more than migrating will. - **Unfixable safety.** The type cannot be made safe for concurrent use, or the API forces a leak that no additive change can plug. - **A contract that blocks everything.** A shape so wrong that every future feature has to be bolted on sideways; the accumulating cost of the workaround exceeds the one-time migration. And the list of things that do not justify it: naming, symmetry, a nicer parameter order, wanting a cleaner surface for new readers, and the fact that the current design embarrasses you. Those go in the deprecation notice and wait for the next major version, or wait forever. ## The parts people forget **Nobody is dragged onto a new version — until they are.** Publishing a tag does not upgrade anyone directly, since version selection resolves to what modules actually require. But a shared dependency that bumps its requirement on you moves everyone behind it, so "they can just pin" is only true until a third party makes it false. Plan for the transitive path, and retract a tag that shipped a break you did not intend. **Deprecation without a deadline is permanent.** Every deprecated symbol you ship without a removal release and a named owner is surface you maintain forever. State the release in the notice, publish a table of what goes when, and check the usage before the date rather than the week of it. **Automate what you can.** If you can ship a mechanical rewrite for the common call sites, the migration becomes an afternoon rather than a quarter, and the political argument disappears with the cost. Even a precise migration guide with before/after snippets per pattern changes the answer you get from teams. **Announce before you tag, not with the tag.** Give the affected teams the deprecation, the reason, the window and the migration path in advance, and ask the two largest importers to try it. They will find the case you did not model, and their agreement is what makes the deadline real. ## How I would answer in one line Break when leaving it alone keeps handing callers wrong results; otherwise grow the surface additively, mark the old path deprecated with a named replacement and a removal release, and spend the major version only when the organisation has agreed to pay for it.