The Case for Tech Migrations: Challenges to Overcome and Key Takeaways

If you have been around in tech for a while, like me, especially in the consultancy sector, you will notice one thing. Sooner rather than later, you are flown in as a consultant to help with a migration of a kind. Or a migration is part of the project that doesn’t cover your specialty but will impact your work on one point while working on the project.

In this blog, I will outline some of the challenges and lessons I have learned while working on several migrations. But first, some background and context.

Background

Two types of migrations I often encounter during my projects for clients are of either one of these types.

The first type is having an old framework, say AngularJs, that needed to be phased out and replaced with a newer framework. Say React or Vue. Commonly, the chosen solution for these kinds of migrations is to build the application from scratch.

The second type of migration involves the upgraded and old version of a framework or library to a higher version. Often, this work should be straightforward. These days, a lot of frameworks have guides or even scripts (openrewrite, for example) to help migrate to a higher version. However, this is only the case when people have adhered to the standards of the frameworks in the first place. Other times, there would be breaking changes in the framework (often for good reasons), resulting in a longer, more difficult migration.

Why Migrations Happen

The reasons for these migrations are varied and very dependent on factors like the age of the software application, the people and their expertise, and the speed of software development at the time of joining.

To explain the latter, often, when applications become more complex, development time increases because, over time, hacks get built in, and fixes and more hacks are built on top of those. This relates to the age of the software application, but this also happens in applications that have not have not been around for more than five years. A high turnover of developers could be the cause. This would result in a mixing of patterns and libraries.

There can be both technical reasons and business reasons to start a migration. A technical reason could be that the support for a framework (or version) has stopped. Another technical reason could be that the framework has reached its limit in solving the specific problem. An example is when organizations migrate to the cloud, which enables the applications to be more scalable. Something that is often not possible or very costly with their current solution.

A more direct technical reason could be that solving major tech debt has been postponed, thus leading to a slow development pace. Since every feature that needs to be built involves some kind of refactoring.

A more business-related reason could be possible cost-savings by switching to a new framework. Or to make the technical stack more uniform across different departments.

I use this definition of migration rather than tech debt because of the amount of time and effort a migration takes. With ‘simple’ tech debt, it would be preferable to do some boy scouting and, when encountering the specific case of tech debt, to include this in the current story that’s being worked on. Or to stretch the story a little and do some extra refactoring, extending the time of the story by a couple of days.

The migrations that I am talking about usually take at least three months, most often closer to six months, and if big (especially when databases get involved), maybe even a couple of years.

Lessons on Migrations

Now, let’s dive into some lessons I’ve learned during migrations.

1. Migrations Always Take More Time Than Expected

People can be managers, developers, or other relevant parties always underestimate how long the migration is going to take. I don’t think this has to do with the lack of skills of either a developer or manager. Rather, there are a lot of uncounted factors or some setbacks that have come up during the migration process. And these factors are on top of the usual factors, for example, people being absent for holidays, etc. As a developer myself, it is also very tempting to say that when the development is finished, my job is done. However, we, as developers, are often not the users of the application that we have built. In these cases, a lot of (regression) testing needs to be done to see if everything still works as it did before. This, in turn, often involves many different parties and costs extra time.

Lesson: Always include extra time in your plan.

2. Plan Ahead

Another thing that sometimes happens is that no plan is made beforehand. This can have several reasons, for example, the updates seem quite small and thus should not take a lot of time. Or a developer doesn’t get the time to work on the tech debt till the point it is severely blocking and just starts himself. In these cases, a lot of surprises tend to come up, so I advise against it. A good plan can help set expectations and keep the mind focused on the goal. Also, breaking up the migration in chunks, if possible, makes it easier to implement code for the migration. Lastly, having written good tests will also make the migration easier.

Lesson: Always create a plan and have an overview of what needs to be done.

3. Communication is Key

Communication is key in these often-long processes, not just between the developers but also the non-technical team members. It helps to decrease frustration and, thus, setbacks when people are being kept up to date and being notified of setbacks. It also helps to take the perspective of others. A little empathy for each other’s circumstances can go a long way. Personally, it always helped me to sit with a person to ask for clarification or to plan a meeting to see if the team members are still aligned.

Lesson: Take the time to regularly align with your team and stay open-minded to prevent frustration.

4. Know When to Make Trade-offs

In some cases, tradeoffs need to be made. As a developer, I would like the code to be way better than what has been written before. But sometimes, doing that during an already lengthy process could extend the migrations by an extra couple of weeks. In these cases, choosing a slightly quicker fix and boy-scouting these fixes after the migration is finished can be a solution.

Lesson: Understand where you can make trade-offs and when compromise is necessary.

5. Be Knowledgeable About Both the Old and New Frameworks

I think migrations can also be more difficult, just like the other tech debt, than coding features. It is necessary to have a good grasp of the old framework, an understanding of what was being done, and the new framework, which may have a different solution for solving the same problem.

Lesson: Make sure you’re well-versed in the topic of migration to better estimate the work and time required.

6. Even If You’re Not Involved in the Migration, It Can Impact You

Even when there is a migration that doesn’t involve your specialty, a migration can impact you. There have been times when the project where I was working on had a backend or cloud migration going on. Even though it was not the focus of my activities, it often did impact me in some other way. This could be something like not having a functional test environment or not being able to deploy the feature that I was supposed to deliver. Again, I think communication is key, but not being afraid to ask what is going to happen helped me to plan around these instances. I noticed it also showed my interest in my fellow developers, which helped to make communication even easier.

Lesson: Stay informed about migrations, even if you're not directly working on them.

7. Help Where You Can

And lastly, don’t be afraid to help. Of course, there are moments when trying to help will only slow the process further, but especially when few people are involved in the migrations, it can be a slow process, a couple of people can only do so much in a day. In these cases, not helping with the main tasks, the development, but the testing and communication can help. After all, I believe software development is of higher quality when team members work well together.

Lesson: Remember that migrations are team efforts—helping each other out will make the process go more smoothly.

Conclusion

Above, I explained some of the challenges and lessons I learned. To summarize:

• Migrations always take more time than expected
• Prepare beforehand, preferably with a solid plan
• Communication is key to successful migrations.
• Sometimes, compromises are necessary
• Know both the old and new solutions well
• Stay informed, even if you're not directly involved.
• Help each other out