From AngularJS to Angular : a 2.5 years migration journey

When I realized I spent 2.5 years migrating an AngularJS application to Angular (among other things), I thought it would be worth telling the story.
The aim of this text is not to present in detail the technical challenges we met nor the solutions we chose, but to explain the journey we undertook while replacing every single line of code in our application codebase.
My idea is to share the mistakes we made, the pitfalls we fell into, and the advice I can give to anyone who is about to begin such endeavor.

To give you an idea of the application size, our github repo counted

• 118'030 lines of code
• 1'706 files

in the application src/app folder (typescript, html and scss files included) rightafter the migration was completed.

A graphical view being always better than a long explanation, here you will find the project and related events timeline

Of course we made mistakes during this migration and here are the biggest ones :

1. We completely neglected automated tests
2. No technical project manager was following the migration

Could it have been otherwise ?

1. When we started the migration, it was high in the company priorities, because we needed a faster application on mobile devices. Unfortunately, it was soon deprioritized in favor of higher business-value projects. Thus the migration had to be done in a “best effort” mode. We knew that it could be stopped anytime if all front-end developers were suddenly required for a more important project. There was a non-negligible risk of keeping a hybrid application forever.
   In addition, migrating brought no business value since the application was working fine in hybrid mode, and there was no infinite budget “just” for technical migration.
   Thus doubling the amount of time for writing unit tests would have been a enormous risk in that regard.
2. I think the whole migration should have been supervised by a technical PM. This would have allowed to better scope the work, and might have helped us to give an approximate deadline for the end of the project.

During this 2.5 years long process, the more important challenges were :

To keep serving the business everyday.
We could not just say “hey no I cannot do this, please wait until the end of the migration”. We had to accept that adding business features was more important than our technical migration.

To keep the developers motivation high.
Working on such a big migration is sometimes thrilling, sometimes depressing :

• When there is no clear vision on the amount of remaining work you feel like working on the middle of this :

• When the project is deprioritized again and again, you have the feeling that no one cares, which is really frustrating. But why would the business care ? There would be no visual changes to see and no visible added value for the clients. Yes the application would load and run faster, but we had no means to estimate how much faster.
• When the framework is evolving at the speed of light, you know that you’ll never be done (which is also exciting, can’t wait for Angular 9!)
• When we started the migration, there were very few documentation on the web, we had to make a lot of choices without having any idea of the possible outcomes (yes, as in life in general)

Not to lose face when we were asked when the migration would be over.
We had no answer to this question, but showing that we believed in the migration success and benefits was enough for the ones asking.

Although we crossed difficult times, we have to be thankful because the worst-case scenario never happened : we’ve never been asked to stop the migration and we have to be thankful to our CTO who always had full trust in us and in the choices we made.

What are the next steps ?

We have been running Angular code for quite some time now but due to the hybrid state we weren’t able to make use of all sets of features and optimization capabilities of Angular framework. The next steps will be :

• Use modules pre-loading for certain modules instead of lazy-loading
• Use Angular 8 differential loading
• Migrate to Angular 9 and Ivy
• Write (a lot of) automated tests

As a conclusion, I would like to give you some advice regarding a hypothetical migration. What should you do and what should you avoid ?

DOs

• PoCs : write PoCs for every new techno or new concept you wish to use. This will give you trust in your choices or show you you have to make another one
• Write clean code : this will ease the unit tests writing
• Stay focus on your target : postpone what can be done later
• Be organized : write all the stories from the beginning to keep track of the work in progress. If you are using Jira, divide the project into several epics. Keeping a huge epic that never ends is a source of demotivation.
• Consider it as a real project, not as something you do when you have time (even if in practice it will be the case)
• Start migrating asap : do not wait for n versions of the framework to be released before starting.
• Keep your team motivated, even when you’re starting to lose hope
• Test : maintain automated tests if they exist, and write new ones as much as you can
• Attend conferences : this brings you new ideas and keeps your motivation high
• Be patient : you will make it
• Party when it’s live (and no so far from bug-free) :-)

DONT’s

• Do not lose hope (remember, you will make it)
• Do not commit a date if you are not able to give estimations. This will avoid you losing your credibility, and being under useless pressure when the impossible deadline comes close
• Do not keep working on parallel branches in your VCS for too long
• Do not plan a big bang unless you’re certain you can hold the deadline
• Do not interrupt the migration : even if it seems to never end, keep migrating. Interrupting a project is the biggest source of frustration for all the people involved, and you don’t want to have a legacy application forever in your codebase.

Thanks for reading and feel free to give feedbacks.