What does a good migration look like?

For what you described, which is a large scale code change, I think doing it incrementally is how I'd go about it. You incrementally "merge" your small change back into the "main" branch. That way,

• you don't have to whole hog test and release everything
• you risk only a "small"/contained outage
• you start getting the benefits of the migration from day 1

This approach can be applied to large architectural migrations as well in fast paced teams. Say you have an old stack O1, and you want to move to your new stack O2. Building O2 will take 2 years for the current features that are supported in O1. Meanwhile, team also needs to launch X new features per month to the users. There are a few typical ways of how you can reach your eventual desired state

• Pick sub-systems S of O1 that can extracted out of O1, and implement on O2. You might have to add compatibility layers between O1 and O2. Choose S based on
  • the benefits of moving to O2 are realized as soon as possible
  • minimize the amount of throwaway work on O1
  • balance engineer staffing so that business doesn't slow down too much

I talk about this more in my code quality course here: https://www.jointaro.com/course/level-up-your-code-quality-as-a-software-engineer/how-to-handle-migrations/

There are 2 big components to a successful migration:

1. It's not half-baked: If you're going to migrate code, migrate all the code. Don't just migrate half of it as it will just make the codebase more confusing.
2. Nothing breaks: This one is obvious, but it's easier said than done and people don't realize how many sub-components go into achieving this. Incremental integration is a big one as Lalit mentioned. Having good A/B test + general killswitch infrastructure is also incredibly important (be ready to turn off the new code if it's breaking).

Here's some other great resources that dive really deep into this:

• "How to convince my engineering org to participate in large-scale migration?"
• "Advice on AWS Migration?"

You may also want to consider having a way to toggle between the legacy library and new library in prod easily. This will make it easier to recover from cases where migrating to the new library caused an issue because you don't need to wait for a new build and deploy to go out.

I've worked on projects in the past where we migrated UI components or consumed a new API version. We usually gated the logic behind an experiment just in case we needed to mitigate any issues as soon as possible.