The symptoms are easy to recognise. A migration was scoped at the start of the quarter, a branch was opened with great enthusiasm, and six weeks later the branch is hundreds of changed files behind the main line. Nobody wants to review it, nobody dares to merge it and the original author has been pulled onto something urgent. The migration has not failed, but it has stopped. This article diagnoses why large migrations stall, and then proposes a specific fix: slicing the work into fifteen-minute changes that are small enough to review, merge and, if needed, roll back.
The symptom: a long-lived branch and a growing fear
Start with what you can observe. In a stalled migration you will usually find at least three of the following signs.
- A branch or work-in-progress that is weeks old and keeps absorbing merge conflicts.
- A task board card with a title like “Move to the new database client” and no subtasks.
- Estimates that were revised upwards several times without any new facts.
- Engineers who describe the work as “almost there” for a month.
- Reluctance to touch the affected area for unrelated changes, because it is in flux.
These are consequences, not causes. The cause sits one level lower.
The diagnosis: no safe first move
When people are asked why they have not progressed, the answers cluster around a single theme. The next change feels risky because it depends on a dozen other changes that have not happened yet. An engineer cannot swap a library in one module without first swapping it everywhere it is shared, and cannot swap it everywhere without a test net that does not yet exist. Every possible first move is entangled with others, so none feels safe, and the work waits for a moment when everything can be done at once. That moment does not arrive.
A second cause compounds the first: the cost of being wrong is large. A change that touches fifty files cannot be reasoned about in a review. Reviewers skim it, which means defects slip through, which in turn makes the author nervous about merging. The size of the change raises the risk, and the risk lowers the willingness to ship, and so size keeps growing.
The fix: slices that are safe on their own
The remedy is to arrange the work so that each slice can ship independently, leave the system working and be undone with a single revert. Several well-known techniques make this possible, and they all share a pattern: add the new thing beside the old thing, move the callers a few at a time, then remove the old thing.
Slice one: make the seam
Before moving anything, put a thin wrapper around the thing you intend to replace. Every caller goes through the wrapper, and the wrapper calls the old implementation. This is a purely mechanical change with no behaviour difference, and it can be done a module at a time. Each module is one sitting of about fifteen minutes: replace the direct calls with the wrapper, run the tests, open a small pull request.
Slice two: add the new path behind a switch
Next, implement the new behaviour inside the wrapper but leave it switched off by default. The switch can be a configuration flag. This too can be done in sittings: one for the new implementation of the first function, one for the second, and so on. Because the switch is off, merging does nothing to production, so the risk of each change is near zero.
Slice three: move callers gradually
Turn the switch on for one caller, one environment or one percentage of traffic, and watch. Each move is a step: flip the flag in staging, compare outputs on a sample, flip it in production for a small slice, record what you saw. If something looks wrong, flip it back. There is no giant release night.
Slice four: retire the old path
Only when everything runs through the new path do you delete the old one, again in small deletions. By this point the removal is boring, which is precisely what you want from the last step of a migration.
A worked example: replacing a database client
Suppose a service uses an older database client library in sixty places and the team wants to move to a newer one. A stalled plan reads “migrate to new client”. A sliced plan reads more like this.
- List every module that imports the old client; paste the list into the tracking card. (One sitting.)
- Write a thin data-access wrapper with the three functions most modules use. (One sitting.)
- Switch the first module to the wrapper and run its tests. (One sitting.)
- Repeat step three for each remaining module, one pull request per module or per small group. (Many sittings.)
- Implement the first wrapper function against the new client, flag off. (One sitting.)
- Add a comparison test that runs both paths on sample input and reports differences. (One sitting.)
- Turn the flag on in staging for that function; compare. (One sitting.)
- Repeat for the other functions, then production, then removal of the old library.
The overall effort is similar to the big-bang version, perhaps slightly higher in raw hours because of the wrapper. The difference lies in risk and visibility. At any point the main line is shippable, the progress is countable and any engineer can pick up any step without needing the full history in their head.
Why fifteen minutes in particular
The quarter hour is not a law of nature; it is a useful discipline. A change that fits in fifteen minutes is almost always small enough to review in five. It rarely touches more than a few files, so conflicts are rare. And the number forces a question during planning: if this step is bigger than a quarter of an hour, what is inside it that can be pulled out? Teams that ask the question consistently find hidden prerequisites, such as a missing test or an unclear ownership boundary, before they run into them mid-change.
For readers who think about the requirements side first, the deep dive on turning web project requirements into an engineering blueprint shows how to pin down what a system must do before it is reshaped.
Measuring whether the fix works
Because this is an engineering problem, test the cure with evidence. Compare the following before and after you adopt slicing for the next migration.
- Age of the oldest open change. Long-lived branches should disappear.
- Size of a typical pull request. Measure by lines or files changed; expect a sharp fall.
- Time from open to merge. Small changes tend to merge within hours.
- Number of reverts needed. Expect more reverts of small changes, but each one is cheap and the outcome is calmer.
Do not expect a magic result on the first attempt. The first migration sliced this way often feels slower because the team is building the wrapper and the habit simultaneously. The second feels noticeably smoother.
Dealing with the usual objections
“The wrapper is wasted effort.” It is temporary scaffolding, and it also gives you a place to add logging and comparison, which pays for itself. “We cannot flag this change.” Sometimes true, in which case slice by data or by component instead of by flag. “Reviewers will be annoyed by so many pull requests.” In practice, reviewers prefer ten five-minute reviews to one two-hour review, particularly because the small ones can actually be understood.
One more place the pattern appears
The same shape, a shared piece pulled out and reached by a defined route, is visible in everyday web products. MotoShareGulf is a web marketplace for two-wheelers, and its users log in through an account service that lives apart from the rest of the site. That is a seam of exactly the kind described above, and it is what makes later changes to login possible without touching everything else. If your migration touches workflow tooling, the write-up about smoothing a workflow with digital automation pairs well with the slicing approach.
What to do on Monday
Pick the migration that is currently stuck. Open its card and write the first three slices in a way that each could be a pull request of under a hundred lines. Make the first one a pure seam with no behaviour change. Ship it today. Then schedule a recurring quarter hour, every day, for the next slice. The migration that looked like a wall will start to look like a queue, and queues are something engineering teams know how to empty.

