Changing a shared interface often looks simple in the code that owns it. Rename a method, replace a parameter, or return a richer result, then update the callers.

The difficulty appears when many callers cannot change at the same moment. They may live in different modules, be maintained by different teams, or be deployed independently. A change that is correct in isolation can then create a period where old callers and new code cannot work together.

Parallel change is a way to avoid that forced coordination. Instead of replacing the old interface in one step, you temporarily support the old and new forms together. Callers move gradually, and the old form is removed only after nothing needs it.

The core idea is simple: add, migrate, remove.

Why direct replacement creates risk

Imagine a pricing component with this interface:

calculateTotal(items, discountPercent) -> Money

The team wants to replace discountPercent with a richer discount policy:

calculateTotal(items, discountPolicy) -> Money

A direct edit changes the contract immediately. Every caller must now pass the new value. If all callers are compiled, tested, and deployed as one unit, that may be acceptable.

But suppose the pricing component is shared by an order workflow, an admin tool, and a scheduled billing job. If those consumers move independently, changing the interface in place creates a coordination requirement: all of them must become compatible before the old contract disappears.

That requirement is the real source of risk. The code change may be small, while the required synchronized change is large.

Parallel change reduces the synchronization requirement by creating a temporary compatibility window.

Think in three phases

A useful mental model is to separate the migration into three phases.

1. Add the new path

Introduce the new interface without breaking the old one.

Conceptually, the pricing component might support both forms:

calculateTotal(items, discountPercent) -> Money
calculateTotalWithPolicy(items, discountPolicy) -> Money

The exact shape depends on the language and API. The important property is compatibility: existing callers still work after the new path is introduced.

The new implementation should become the preferred path. When practical, keep the old entry point as a thin adapter so business logic does not split into two independent implementations:

calculateTotal(items, discountPercent):
    policy = percentageDiscount(discountPercent)
    return calculateTotalWithPolicy(items, policy)

Now both interfaces reach the same pricing behavior. Fixes and rule changes remain centralized.

2. Migrate callers

Move consumers to the new interface one at a time.

The order workflow can migrate first, the admin tool later, and the billing job after that. During this period, old and new callers coexist.

This is the main advantage of parallel change. Each migration becomes a smaller change with a smaller review and testing surface. If one consumer has an unexpected constraint, it does not have to block every other consumer.

Track the remaining old usage explicitly. A deprecated annotation, compiler warning, static search, telemetry, or a migration checklist can help, depending on the kind of interface. The goal is to know when the old path is genuinely unused rather than merely assuming it is.

3. Remove the old path

Once all callers use the new contract, delete the compatibility layer.

calculateTotal(items, discountPercent) -> removed
calculateTotalWithPolicy(items, discountPolicy) -> retained

Removal is part of the migration, not optional cleanup. Leaving both forms indefinitely makes the system harder to understand because future developers must decide which interface is authoritative.

A completed parallel change returns the design to one clear path.

Compatibility is the safety mechanism

Parallel change works because each intermediate state remains usable.

Consider the sequence:

State A: old interface only
State B: old + new interfaces
State C: new interface only

The transition from A to B does not break old callers. While the system is in B, consumers can migrate independently. The transition from B to C happens only after old callers are gone.

This is different from making one large change and hoping every dependent piece moves together. The intermediate compatibility is deliberate.

That distinction matters in systems with independent deployment. If a provider and consumer are released separately, there may be no guarantee about which version reaches production first. A migration should therefore be designed around the deployment orders that can actually occur.

For example, adding a new optional capability before any consumer requires it is usually easier to deploy safely than making an existing required field change meaning overnight.

Keep the compatibility layer narrow

Temporary compatibility code is useful, but it has a cost. For a while, the system supports more than one way to express the same operation.

Keep that period as simple as possible.

A good compatibility layer translates between old and new representations at one boundary. It should not create two separate business implementations.

Suppose an old notification interface accepts an email address directly:

sendReceipt(order, emailAddress)

The new design accepts a delivery destination:

sendReceipt(order, destination)

If the old method can construct an email destination and delegate to the new method, there is still one receipt-sending implementation:

sendReceipt(order, emailAddress):
    destination = EmailDestination(emailAddress)
    return sendReceiptTo(order, destination)

By contrast, copying the entire sending workflow into both methods creates two places for behavior to drift. The compatibility layer should translate; the core implementation should remain shared.

Choose the migration boundary carefully

Not every change needs compatibility at the same level.

For an internal function used in one small module, changing all callers in one commit may be simpler and safer. Adding a temporary interface would create ceremony without reducing meaningful risk.

Parallel change becomes more valuable as coordination becomes harder. Typical signals include:

  • many callers spread across a large codebase;
  • ownership split across teams;
  • components released on different schedules;
  • a migration that will take several changes to complete;
  • a contract used outside the component that owns it.

The useful question is not, “Can we change this in one edit?” It is, “Can every affected consumer safely move at the same time?”

If the answer is no, a compatibility phase can make the change easier to control.

Do not confuse compatibility with permanent duplication

A common failure mode is completing the add and migrate phases but never completing removal.

Over time, temporary APIs accumulate:

createOrder(...)
createOrderV2(...)
createOrderNew(...)
createOrderWithOptions(...)

The original migration risk has disappeared, but the compatibility cost remains. New code may even start using an interface that was supposed to be temporary.

Prevent this by defining the removal condition when the new path is introduced. For example:

Remove calculateTotal(items, discountPercent)
after all three known callers use DiscountPolicy.

For public or externally consumed APIs, removal may require a documented deprecation policy or version boundary. For internal code, the window can often be much shorter. The principle is the same: compatibility has a lifecycle.

Test the transition states, not only the destination

A migration can fail even when the final design is correct.

During the compatibility phase, test the states that will actually exist. The old interface should still produce the expected behavior. The new interface should work correctly. If both delegate to shared logic, tests should confirm that the translation preserves important semantics.

For independently deployed components, also reason about version combinations. If an old consumer can encounter a new provider, that combination must remain valid for as long as the deployment process allows it to occur.

This changes the testing question from:

Does the new interface work?

to:

Are the intermediate combinations we intend to run compatible?

That is a more useful question for staged migrations.

Know when parallel change is the wrong tool

Parallel change is not automatically safer for every refactoring.

If a private method has two callers in the same module, updating all three pieces together is usually clearer. A compatibility layer would add code without buying useful independence.

It can also be a poor fit when old and new semantics cannot coexist safely. If supporting both interpretations would make data ambiguous or violate an invariant, the migration may need a controlled cutover instead. In that case, explicit coordination is better than pretending the versions are compatible.

There is also an operational cost. Temporary paths need tests, observability where relevant, ownership, and eventual removal. Use parallel change when that cost is lower than the risk and coordination cost of an atomic migration.

A practical migration checklist

Before changing a shared interface, identify its consumers and decide whether they can move together. If not, design a compatible new path first.

Then keep the migration disciplined:

  1. Add the new interface without changing the meaning of the old one.
  2. Route old behavior through the new implementation when that translation is valid.
  3. Test both paths and any important mixed-version state.
  4. Move callers in small, independently verifiable changes.
  5. Track remaining old usage explicitly.
  6. Remove the old interface as soon as the migration condition is satisfied.
  7. Delete compatibility tests and adapters that no longer serve a purpose.

The checklist is less important than the ordering. The new path exists before callers depend on it, and the old path disappears only after callers stop depending on it.

Conclusion

Shared interfaces are difficult to change when their consumers cannot all move at once. Treating the change as one atomic replacement turns a local design improvement into a coordination problem.

Parallel change makes the transition explicit. Add a compatible new path, migrate consumers gradually, then remove the old path. The temporary duplication is intentional and bounded.

Use it when independent change matters, keep the compatibility layer narrow, and define its removal condition from the beginning. The goal is not to support two interfaces forever. It is to make each intermediate state safe enough that the system can reach the better design without requiring one risky synchronized jump.

Software Engineering Refactoring API Design Maintainability