Your team ships an internal chat-transcript archiver library and other services now import helpers you never meant to expose. How do you decide what the public API promises, and how do you version those promises?

## The surface is a liability you choose to take on Every name a library exports is a promise someone will build on and you will have to keep, deprecate or break. That makes surface area a budget, not a byproduct. The default posture for a shared library is private-until-promoted: implementation lives in underscore-named modules, the package root imports the handful of names you intend to support, and `__all__` lists exactly those. Promotion is a deliberate review decision, because you are signing up to version the name from then on. A second, easily-missed part of the promise is the *import path*. If callers can reach the same class as `archive.Archive`, `archive._core.Archive` and `archive.core.Archive`, you have three promises for one object, and moving the implementation breaks two of them. Publish one path, document it, and keep the rest underscored. ## What counts as a breaking change in Python The version number is only useful if everyone agrees what a break is, and Python's dynamism makes the list longer than newcomers expect. All of these break callers even though the code still "works": * Renaming a parameter — callers pass it by keyword. * Changing a default value, or making an optional parameter required. * Moving a name to another module, or removing it from `__all__`. * Raising a different exception type, or a new one, from an existing call. * Narrowing accepted input types, or widening returned types in a way annotations reveal. * Dropping support for a Python version, or for an operating system or architecture you had wheels for. * Changing the semantics of a value while keeping its shape — the change nobody's type checker catches and everybody's tests miss. Write that list down in a compatibility policy, because a team that has not agreed on it will ship all seven as patch releases. Note also what is explicitly *not* covered: anything underscored, anything reached through a non-documented path, and behaviour you never specified. Saying what you do not promise is as valuable as saying what you do. ## Tying the promise to the number the installer reads The published version is the machine-readable form of the policy: consumers pin against it and resolvers act on it. Make it single-sourced so the number in the distribution metadata cannot drift from the source tree, and make the release process, not a person, own the bump. Then choose a scheme and mean it. A `0.x` line is a legitimate way to say "no compatibility promise yet", provided you leave it before other teams depend on you. A date-based scheme suits a library whose changes are continuous and whose consumers upgrade in lockstep, but it gives resolvers no signal, so it fits an internal monorepo far better than a published package. Whatever the scheme, the version is worthless without a support window. State how long a deprecated name lives and how many releases back you will patch, so consuming teams can plan rather than react. ## The helpers that got imported anyway Take the concrete case seriously rather than as a discipline problem. Suppose one service's archiving job holds a 2.4 GB working set because the public `load_transcript()` returns the whole transcript, so its authors went to `_stream_chunks` instead. The convention worked exactly as designed — it told them they were on their own — but the pull was real. Policing the boundary without closing the gap just moves the workaround somewhere worse. The sequence that works: measure who imports what, and why; fix the API gap by promoting a supported streaming entry point; migrate the callers; then remove or rename the private helper once nothing points at it. Add an automated check so new private imports fail review rather than accumulating. Where a private name has become so widely used that migration would cost more than supporting it, the honest move is to adopt it — promote it, document it, and take on the versioning obligation — not to leave it underscored and pretend the promise does not exist. ## Where the boundary sits for an internal library Being internal changes the economics, not the principles. You can see every caller, so you can remove things faster and with real evidence, and you may be able to land the migration in the consumers yourself. What you cannot do is skip the announcement: an unannounced break in a shared library costs several teams a day each, and that cost is invisible to the team that saved an hour by not writing a deprecation shim. The deal to strike is a small surface, a clear compatibility policy, an honest version number, and a support window short enough that you are not carrying shims forever but long enough that nobody's release is hostage to yours.