The Migration Is the Product

Every platform I have worked on had a launch. A date, a deck, a demo, an announcement in a channel with a rocket next to it. And every one of those launches was the least consequential day in that platform's life. The day that mattered came later, when a team with a working system and a full quarter of their own commitments had to take theirs apart and put ours underneath it.

That is the day a platform is actually experienced. Not as an architecture, not as an API surface, but as weeks of somebody else's roadmap spent on your behalf. If you have ever wondered why adoption stalls among the teams who already said yes, this is usually where it stalled.

What the customer is actually buying

When an internal team evaluates your platform, they are not comparing your design against the alternative design. They are comparing two futures: one where they keep the thing that already works, and one where they spend real weeks on a change they did not ask for. The second future is what you are selling, and the migration is its entire content.

This is why a technically better platform loses to a weaker one with a better path in. The decision is made by people who have to justify the quarter to their own leadership, and a platform that makes that justification easy has won before anyone opens the design doc. The same logic sits under why adoption is the thing that separates a platform from a library: a team with a real alternative chose you, and the migration is the price you asked them to pay for choosing.

Where the promise gets tested

I have argued that a platform is a promise that someone else's roadmap is safe on top of yours. A migration is the first time that promise costs the other party something real, which makes it the first time it means anything at all.

Everything a customer team quietly suspects about you is either confirmed or refuted during the move. Whether your documentation describes the system you actually run. Whether their edge case gets a fix or a paragraph explaining why it is their edge case. Whether your on-call answers when the thing that broke is the seam between the two of you.

A migration is the only part of your platform that every customer is guaranteed to experience. It is not the cost of the product. It is the product's first honest demo.

Teams generalize hard from this, and they talk. One bad migration does not cost you one customer. It prices every future migration for everyone watching, because the next team's evaluation now includes a rumor about what working with you is like.

Design the migration like a product

If the migration is the product, it needs what a product needs: an owner, a backlog, a design, and a quality bar. Most platform organizations treat it as a rollout instead, a spreadsheet of team names against target dates, owned by a program manager, with the engineering work silently assumed to belong to the customer. Four things change when you invert that.

1. The first mover is a design partner, not a pilot

A pilot tests whether your plan works. A design partner tells you what the plan should have been. Choose that first team for how bluntly they will tell you the truth rather than for how clean their system is, and put one of your own engineers inside the move for its full duration. What you learn there is the specification for every migration after it, and you only get to learn it once cheaply.

2. Build the paved road before you set the date

A deadline does not reduce the work. It relocates who ends up doing it badly, under time pressure, in a part of the system you cannot see. Ship the automated rewrite, the compatibility shim, the one-command bootstrap and the harness that proves the old and new paths agree, and then publish the date. The order is the message, and everybody reads it correctly.

3. Make the retreat cheap

Nobody wants to be the team that cannot get back. A reversible migration gets adopted faster than a better irreversible one, because the decision stops having to be right the first time. Dual running, shadow traffic and a documented rollback are not an admission that you doubt your own quality. They are the reason a cautious team can say yes this quarter instead of next year.

4. Measure their experience, not your progress

Share of teams migrated measures your quarter. The time from a customer team's first commit to their first working path in production measures theirs. Only one of those tells you whether the product is any good, and it is not the one that looks tidy on a leadership slide.

The part nobody plans for

Every migration has a long tail: the service with no owner, the integration that exists only inside a scheduled job, the team that is halfway through a reorg. The tail is where migrations die quietly. Not because the remaining work is hard, but because accountability evaporates after the celebration and the stragglers become background noise.

Two decisions make the tail survivable, and both are unpopular. Name the day the old path stops being supported, and treat that date as a promise to the teams who already moved, because they are the ones paying for the stragglers in features you cannot ship while you carry both. Then decide out loud whether a permanent two-system state is acceptable. Sometimes it genuinely is. What is never acceptable is drifting into it while the roadmap still describes a migration in progress.

What this changes about staffing

The inversion has one consequence that makes it real rather than rhetorical: migration work belongs on your roadmap, in your headcount, with your strong engineers on it. Not a rotation. Not the thing a new hire picks up to learn the codebase. Not the work that happens after the feature work, which is to say never.

That is expensive, and the trade is still favorable. Migration tooling is close to the only platform investment that compounds across every future customer, and the alternative is paying for the same work over and over in other teams' quarters, where you cannot observe it, cannot improve it and cannot reuse any of it. Build versus buy turns on who holds ownership afterwards, and this is that same question asked about a capability of your own.

None of this is domain specific, which is the part I find most useful. The migration was the real product when the system underneath was content, when it was data, when it was payments, when it was connected devices, and when it was a pharmacy ordering flow in its first years. The vocabulary changed every time. The quarter somebody else had to spend never did.

The platform you designed is the thing you believe you are shipping. The migration is the thing people actually receive. When those two stop matching, the migration wins the argument, because it is the only one anybody has to live through.

Haseeb Afsar