Large migrations fail when the team treats “the new version” as a single moment. Real systems need a sequence of changes that can be observed and recovered.
Start with a vertical slice
Choose one useful workflow and carry it through the new route, controller, service, data access, view, logging, and test layers. A vertical slice reveals integration problems earlier than migrating an entire layer in isolation.
The slice should include an ordinary success path and at least one failure path. Authentication, validation, missing data, and database mismatch errors are part of the feature, not post-migration polish.
Compatibility is a tool, not a destination
During transition, adapters and fallback configuration can keep the application running while dependencies move. They should be explicit about precedence and failure behaviour.
For example, configuration can prefer modern connection-string keys while recognising a legacy environment variable long enough to diagnose deployments. That is safer than silently accepting multiple values forever.
Diagnostics belong in the design
Migration diagnostics should answer:
- Which environment is running?
- Which configuration provider supplied a value?
- Which database provider and target were selected?
- Did external authentication complete its callback?
- Did the session cookie survive the redirect?
- Did the database initialise successfully?
The answers should be observable without logging secrets or sensitive records.
Make failures non-mysterious
Graceful startup can be useful, but it must not hide an unusable application. If database initialisation is non-fatal, expose a health or diagnostic path and log a clear warning. If a feature is unavailable because configuration is missing, return a useful error rather than a generic failure.
The lesson
Incremental migration is a feedback system. Ship small slices, instrument the boundaries, preserve safe fallbacks, and remove compatibility code only when the replacement is proven.