Incremental Code Migrations
Tags: codemigration, phasedmigration, rewrites, rewrite
Published: 2020-11-09 22:18:50

---
title: Incremental Code Migrations
published: true
date: 2020-11-08 00:00:00 UTC
tags: 
  - codemigration
  - phasedmigration
  - rewrites
  - rewrite
canonical_url: https://addyosmani.com/blog/incremental-migrations/
cover_image: https://dev-to-uploads.s3.amazonaws.com/i/2dkxekuqgxu7jsdwksf8.jpg

---

**Incremental migrations are excellent for updating large legacy projects - migrate a small piece at a time with lower risk then gradually do the rest.**

Incremental migration strategies for large legacy software systems include breaking down the system into smaller components that can be selectively and individually replaced. This phased migration reduces the expense and risk of a migration compared to doing all of an update or rewrite at once (e.g a phased migration to TypeScript, ES Modules or a newer version of a framework). In some cases, some of the legacy components might be encapsulated in wrappers so they can be used in their original form until new components with a decent degree of reliability can take over their function. 

A [phased migration](http://www.dcs.ed.ac.uk/home/rgd/sw/migrateIncrementally.html) from the legacy architecture to the target one can have a lot of benefits. When done well, there can be a fully functioning hybrid legacy/target version of the system running in production while getting key insights into what works and what has rough edges. You may wish to prioritize the order in which phases of your migration take place keeping in mind what the most pressing objectives need to be tackled first. Alternatively, first tackle mission-critical stages to lift the profile of the project and get buy-in to see through the full migration.

<img src="https://dev-to-uploads.s3.amazonaws.com/i/qx2yn7iqe03rp81e6181.png" width="640px" alt="incremental migration, parallel adoption and big bang adoption."/>

Since the system is still operational after each phase of the migration, it is possible to appreciate the benefits of the project faster than if the entire legacy were migrated and implemented at once. Often, bugs in a small component are easier to identify and fix than in a large system. This decreases the risk and inconvenience of the project to users. 

There are a number of alternatives to incremental or [phased migration](https://en.wikipedia.org/wiki/Phased_adoption), including:

* [Big bang adoption](https://en.wikipedia.org/wiki/Big_bang_adoption) where a full migration is rolled out on an agreed on date, replacing the old system with a new system. This is effectively an instant changeover.
* [Parallel adoption](https://en.wikipedia.org/wiki/Parallel_adoption) where both old and new systems run in parallel (simultaneously) for a time, until the implementation of the new system is considered complete.
* Pilot conversion where a very partial migration is rolled out to a group of trusted testers for evaluation before the implementation rolls out to more users (e.g trying out a migration for a specific component or page).

I tend to favor incremental migrations for many reasons, including that lessons gained from phased migration phases can be used to direct the remainder of the project. That way as the implementation progresses, there are ideally fewer issues.