Branch by Abstraction

Create a seam before replacing behavior

Branch by abstraction replaces an implementation gradually while the main branch remains releasable. First introduce an interface or abstraction in front of the legacy behavior. Route existing callers through it without changing observable results. Then implement the new behavior behind the same contract and migrate callers or traffic incrementally. This avoids keeping a large feature branch open while teams independently change the same codebase.

The abstraction should represent a stable capability, not mirror every method of the old class. For example, an old pricing module may expose database details and framework types. A new PricingPolicy interface can express quote and adjustment operations in domain terms, with the legacy module adapted behind it. The boundary makes replacement possible, but it does not guarantee the interface is correct; tests must define the behavior callers rely on.

Migrate in controlled steps

The safe sequence is to characterize existing behavior, add the seam, route callers through the old implementation, and release that change. Then add the new implementation, compare outputs or use a limited traffic switch, and migrate consumers in small steps. Keep rollback possible while the new path is being validated. Once every caller uses the new implementation and the old path is no longer needed, remove legacy code, temporary switches, and compatibility scaffolding.

Feature flags can select implementations or cohorts, but they introduce state and operational risk. Give the flag an owner, default, monitoring plan, and removal date. Ensure both implementations satisfy the same contract and that switching does not corrupt data or duplicate side effects. A flag that lives forever creates two production paths that teams must test and operate indefinitely.

Keep behavior compatible

Characterization tests capture important current behavior, including odd edge cases that callers may rely on. These tests do not declare every legacy behavior desirable; they make changes visible so the team can decide whether to preserve or intentionally alter it. Contract tests at the abstraction boundary prevent the new implementation from violating assumptions about ordering, errors, null handling, or transaction scope.

If both implementations can run in parallel, compare safe outputs without executing side effects twice. A shadow mode can compute a new result and log a sanitized difference while only the old result affects the user. For writes, dual-writing requires consistency, idempotency, and reconciliation; it is not a harmless comparison technique. Avoid exposing sensitive data in diff logs and define how discrepancies are reviewed.

Manage rollout and removal

Move callers or traffic in observable stages. Define success measures such as error rate, latency, data consistency, and business outcome. Set a rollback threshold and verify the old implementation remains usable until confidence is sufficient. If the migration changes data format, plan compatibility and backfill separately from the code switch. A code abstraction cannot solve an unsafe data migration on its own.

The pattern is most useful for a high-risk replacement that must ship continuously. It may be unnecessary for a small isolated module that can be replaced and tested in one short change. It also cannot compensate for an abstraction with no meaningful boundary. The work is complete only after the new path is default, old code and flags are removed, and operational ownership is clear.

Replace a legacy pricing implementation

Assume several services call a legacy pricing library directly. It reads a database, uses framework-specific types, and returns a vendor-shaped discount object. The migration goal is to introduce a new pricing engine without blocking releases. First identify the caller behaviors that matter: currency rounding, discount precedence, error semantics, and transaction boundaries. Add characterization tests around representative and boundary cases before changing call sites.

Define a small domain interface such as quote(cart, customerContext) returning a local PriceQuote. Implement a LegacyPricingAdapter that calls the old library and maps its result. Update one caller to use the interface and verify that it still uses the legacy implementation. Release this structural change independently. The release proves the seam is safe before the new engine enters the path.

Introduce and compare the replacement

Implement NewPricingEngine behind the same interface. Test it against the contract and compare its behavior on recorded, sanitized inputs. For read-only calculations, shadow evaluation can compute both results and record differences while the legacy output remains authoritative. Classify differences as expected policy changes, defects in the new engine, or previously unknown legacy behavior. Do not run writes or external side effects twice merely to compare outcomes.

If results are acceptable, route a small cohort to the new engine with an observable switch. Monitor price discrepancies, error rates, latency, and support reports. Include a rollback switch and verify it before increasing traffic. If pricing results affect persisted invoices, define a reconciliation and audit strategy; switching back cannot undo an already-issued charge. Use an idempotency key and a controlled migration boundary for irreversible effects.

Migrate callers and retire the old path

Move remaining callers to the abstraction in small changes. Some consumers may need a new domain contract; adapt them explicitly rather than leaking the legacy result to preserve convenience. Keep ownership visible and track which consumers remain. Once every caller uses the new implementation, make it the default and observe it through a defined stability window.

Remove the legacy adapter, implementation, comparison mode, temporary flag, and unused dependencies. Delete characterization tests only if their contract is intentionally retired; otherwise keep the behavior test at the new boundary. Update the architecture record and runbook to describe the new implementation. A migration that leaves both code paths indefinitely has not completed the replacement and continues paying for complexity.

Exercise rollback and data risk

Test rollback before rollout by switching a non-production cohort back to the legacy implementation. Verify that the switch does not change persisted state unexpectedly and that dashboards identify which implementation handled each request. If data was backfilled, test partial completion, duplicate execution, and resume behavior. Define a reconciliation report for records that differ between the two representations.

Branch by abstraction is a sequence of compatible changes, not one large refactor disguised as a feature flag. Each step should be independently deployable and observable. The abstraction stabilizes callers, tests protect the contract, and gradual rollout limits exposure. Removal work is part of the plan from the beginning, so temporary dual paths do not become permanent architecture.

The abstraction can become the new legacy

An interface that mirrors the old implementation preserves old coupling under a new name. Design the seam around the capability callers need and keep infrastructure types behind adapters. Do not create a generic plugin system for one migration unless the domain has a real need for multiple implementations. The abstraction should reduce the cost of change enough to justify its code and ownership.

Parallel implementations create drift risk. Contract tests should define behavior, and rollout metrics should reveal divergence. Shadow comparisons must avoid duplicate side effects and sensitive data exposure. Feature flags need a removal plan; otherwise both code paths remain in production and every future change multiplies testing and operational work.

Plan rollback before cutover

Rollback is not always a code toggle. If the new path writes a different schema or triggers irreversible actions, reverting the implementation may be unsafe. Plan expand-and-contract data changes, compatibility windows, reconciliation, and idempotency. Define the point after which rollback means forward repair rather than switching back. Communicate that boundary to operators and decision owners.

In an interview, explain the sequence: characterize, introduce the seam, route through the old implementation, implement and validate the new path, shift consumers or traffic, then remove the old path. Describe how contract tests and telemetry limit risk, and give one rollback condition. Explain when a short direct replacement is simpler. That answer shows branch by abstraction is a continuous-delivery strategy with an explicit end state, not a permanent layer of indirection.

A migration plan should assign an owner to the abstraction, the new implementation, and the cutover. Track caller adoption so the team knows whether a hidden legacy dependency remains. A code search can help find direct imports, but runtime telemetry or dependency instrumentation may be needed when callers are dynamic. Define the evidence required to remove the old implementation and the date or milestone for deleting the switch. Without an explicit completion criterion, the temporary design can become the default indefinitely.

Test the rollback path using realistic state. If both implementations read the same data, switching back may be straightforward; if the new implementation writes a different representation, rollback may require a compatibility reader or a forward-fix plan. Expand-and-contract migrations can preserve old and new formats during a transition, but dual support has a cost and a defined end date. Verify that rollback does not duplicate events, lose updates, or route one tenant through inconsistent implementations.

Keep the abstraction observable without leaking sensitive payloads. Include a low-cardinality implementation identifier in metrics, compare error rates and latency by path, and record safe discrepancy categories. Do not use customer ids or raw values as metric labels. A gradual rollout needs a cohort definition, a stop threshold, and an operator who can execute the switch. Test the flag's default in each environment so a configuration mistake does not send all traffic to an unvalidated path.

The technique is less useful when the replacement is small, isolated, and can be shipped in a short atomic change. It can also be unsafe when old and new implementations cannot coexist because of exclusive locks, incompatible writes, or external side effects. In those cases, use a planned maintenance window, data migration, or staged interface version instead. State the constraint that makes gradual coexistence viable before choosing branch by abstraction.