An internal deployment platform with six engineers serves 40 product teams. Three versions of its pipeline interface are live - v1 with 22 teams on it - v2 with 15 and v3 with 3. Supporting all three consumes roughly 40% of the platform team's capacity in compatibility work and support, and the team has shipped no new capability for two quarters. Which versioning policy should the platform adopt?

The deciding property

Where the migration work sits. Spread across 22 consuming teams it is 22 separate decisions competing with 22 roadmaps; concentrated in the platform team it is one piece of engineering work with an owner and a date. A platform team of six against 40 teams cannot win 22 negotiations, and it does not have to.

The policy

Publish a support window per version — a plausible shape is new version supported from release, previous version supported for 12 months from the successor's release, and nothing older — and state it before the next version ships, because a window announced retroactively is a mandate wearing a different hat.

Then do the arithmetic that justifies the tooling. Migrating a team by hand costs roughly 2 to 4 engineer-days of the consuming team's time, so 22 teams is on the order of 60 engineer-days spread across people who did not ask for the work. A migration script that rewrites the common pipeline shape costs the platform team perhaps 10 to 20 days and covers most teams, leaving a handful of unusual cases to help by hand. That is a cheaper total and, more to the point, it is a cost the platform team can schedule.

Why the other options fail

• Support until the last consumer leaves. This is the respectful-sounding default and it is how a team arrives at three live versions and 40% of capacity gone. The liability is open-ended because the last 10% of consumers have the least incentive to move and the most unusual usage, so the tail is the expensive part and it never ends on its own.
• Mandate v3 in one quarter. This fails on capacity, not on principle: 22 teams rescheduling inside one quarter is not something a six-person platform team can support, so teams either stall or fork their own pipelines, and the platform has converted a technical problem into a trust problem it will spend a year repairing.
• Freeze the interface permanently. Attractive, and it moves the cost rather than removing it. Every change now arrives as another flag, the flag combinations become the real interface, and the compatibility surface grows faster than versioned interfaces would have.

What it costs

A support window is a promise, and promises constrain. The platform team must keep a compatibility shim and a test matrix for the whole window, and it must refuse late exceptions or the window means nothing. Budget the shim as ongoing work, not as a project.

When not to version at all

When a version has fewer than roughly three consumers, do not build tooling — sit with each team and move them, which is days rather than weeks. And for an interface used by five teams rather than 40, skip formal versioning: coordinate the change in a shared channel and move everyone in one release. Versioning policy is a response to consumer count, and below a handful of consumers it is pure overhead. The tell that you crossed the line is the first time a change to the interface breaks someone in production whose pipeline you did not know existed.