What is the Branch by Abstraction pattern for incremental migration?

Branch by Abstraction is an incremental migration technique that replaces an existing component without disrupting the codebase or requiring a long-lived code branch. The key mechanic is introducing an abstraction (an interface or abstract class) over the existing component so that all callers depend on the abstraction rather than the concrete implementation. The replacement is then developed behind that same abstraction and switched in when ready.

The four-step process:

1. Create the abstraction — introduce an interface or abstract class that captures the component's contract. Update all callers to program against the abstraction, not the concrete class. The system still works exactly as before; only the coupling direction has changed.
2. Implement the new version — build the replacement (e.g., a microservice client stub that calls the extracted service) behind the same abstraction. Both the old and new implementations exist simultaneously in the main branch.
3. Route clients progressively — use a configuration flag, feature toggle, or simple factory to direct some or all callers to the new implementation while the old one remains available as a fallback.
4. Remove the old implementation — once the new implementation is validated in production and all traffic is routed to it, delete the old code. The abstraction itself may also be removed if it no longer serves a purpose.

The critical property of this pattern is that the main codebase remains in a releasable state throughout the migration. There is no feature branch that diverges from main for weeks; the entire process happens in small, shippable increments on the trunk. This makes it a natural complement to the Strangler Fig pattern: Branch by Abstraction prepares the seam at which the Strangler Fig can extract a capability.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.