A helper type your Go package exported by accident is now imported by three other teams. How do you shrink that surface?

## Why this is hard An exported identifier is not a fact about your code, it is a promise to other people's builds. Once three teams import `migrate.SQLFile`, deleting it does not simplify your package — it breaks three build pipelines. So the work is not a refactor, it is a migration with other people in it, and the sequencing matters more than the code. ## Step 1: find out what you actually promised Before touching anything, get the real list. `go doc example.com/migrate` prints the package's exported symbols with their doc comments — that output *is* your API, and reading it in one sitting is often the first time anyone has. Expect surprises: helper types, a constant that was exported to be used in a test, a struct field raised to upper case for a one-off. ## Step 2: find out what is actually used A code search across the consuming repositories, per identifier, is the diagnostic that decides everything after it. Grep for the qualified name — `migrate.SQLFile` — across every repository that imports the module, and read the hits rather than counting them. Typical outcome: - most hits are the same call, copied between services, doing something your package could do for them in one line; - one or two hits use the type in a way you never imagined, and those are the ones that will fight you; - some hits are dead code, or tests of dead code. That distribution changes your plan. Thirty mechanical uses of one pattern means you write one replacement and send thirty small patches. Three genuinely different uses means three conversations. ## Step 3: replace the need, not the symbol The mistake is to offer the same thing under a different name. Ask what each caller was trying to do. If they exported-type-juggled their way to "parse these files and tell me the order", the replacement is a function that answers exactly that, returning a small result type you are happy to own. The new API is usually smaller than the accidental one, because you are designing for observed needs rather than exposing an implementation. ## Step 4: move the callers In an organisation where you can see the consuming repositories, send the patches. This is the step teams skip in favour of announcing an intention and waiting, and waiting is how a two-week migration becomes a two-year one. Do the work; the diff is usually tiny in each repository, and you are the person who understands both sides. ## Step 5: close the door behind you When the last use is gone: - move the implementation into a package under `internal/`, so the same leak cannot happen again by a future edit; - delete the exported name from the outer package; - if the module is public and versioned, the removal is a breaking change and belongs in a new major version path, not a patch release. Inside a single organisation with a monorepo and one build, the coordination you already did is the release process. An intermediate step that buys time: leave an exported alias or a thin exported wrapper in the outer package while the implementation lives under `internal/`. Existing call sites keep compiling, new code cannot reach the internal package, and you delete the alias when the last caller is gone. ## Step 6: fix the cause Almost every accidental export has the same origin: a helper was raised to upper case so that a *sibling package of your own* could use it. That is exactly the problem `internal/` solves — an internal package can export freely without promising anyone. Ask, at review time, of every newly capitalised name: who outside this module is meant to call this? If the answer is nobody, the letter goes back down or the code goes under `internal/`. ## What to tell the person who wants to just delete it They are right about the goal and wrong about the cost. The surface is genuinely too large and shrinking it is genuinely valuable — a smaller API is less to document, less to keep working, less to test, and less to reason about when changing the implementation. But the bill for exporting was incurred at the moment of export, and the only way to pay it down is the migration above. The cheap version of this work is prevention: it costs one review comment before the merge, and weeks afterwards.