0

What does a good migration look like?

Profile picture
Junior Engineer at JPMorgan Chase6 months ago

Recently, I was helping migrate my team’s entire codebase from a legacy Java DateTime library to the newer, built-in Java DateTime library.

I’ve never performed a migration before, so I don’t have context to know whether this kind of migration is typical (my current team isn’t very good). 

Some of the features of the migration:

  • The codebase primarily contains poorly written unit tests or tests without assertions (and no E2E or integration tests)

  • Consequently, we tested the application by setting up a separate environment, simulating user flows, and manually verifying results inside the DB

  • The migration took over a month to perform - meaning constant merge conflicts from new changes to resolve

What might a migration look like at a good tech company? 

42
3

Discussion

(3 comments)
  • 1
    Profile picture
    Staff Software Engineer [L6] at Google
    6 months ago

    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
  • 1
    Profile picture
    Eng @ Taro
    6 months ago

    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.

  • 0
    Profile picture
    Tech Lead @ Robinhood, Meta, Course Hero
    6 months ago

    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:

JPMorgan Chase & Co. is an American multinational investment bank and financial services holding company headquartered in New York City and incorporated in Delaware.
JPMorgan Chase16 questions