Achievement Unlocked: Migrating FT.com to Page Kit
by Maggie Allen
Recently, my team wrapped up a long project to rebuild and deprecate a critical part of our website, a frontend module called n-ui, on which all of our user-facing apps depended.
The reasons behind the decision to rebuild and the story of how we did it has been covered in this excellent post by Matt Hinchliffe.
In the beginning I was naively reassured by the idea that we had a working application containing all the required functionality readily available to us and the fact that I’ve enjoyed refactoring old code in the past. I assumed that this would be a similar exercise on a larger scale so I was surprised when a conversation with Rhys Evans made me look back on the project and realise how many skills I’d had the chance to hone or acquire along the way.
Check out this excellent post from Rhys Evans about how migrations projects often stretch engineers in unexpected ways.
The first step was to understand everything that n-ui was responsible for and how it all worked. This meant reading and understanding a LOT of code, much of which was poorly understood by the current team or had not been actively worked on for a long time. We quickly coined the term code-archeology for this work, a clue to the fact that this was like no other project I’d worked on. We combed through the code, talked to developers who’d worked on and built the existing module and asked what they valued in the project and what they would do differently if given a chance. We scrutinised the tooling choices and explored what alternatives existed. We started thinking seriously about how we would architect our codebase, about the tools we were choosing and why. I later saw how making choices deliberately at this stage, and being able to justify them, ultimately helped the project stay focused and helped us to see when sections needed to be refactored.
✓ Code-archeology
✓ Justifying technical decisions
Armed with a plan, we began building Page Kit, the new library of packages which has replaced n-ui on FT.com. This brought me into contact with parts of our build pipeline that I wasn’t even aware existed! I employed my new archeology skills to dig into the unknown code, finding and understanding its edge cases, but this only gave me half the picture. I needed to get a lot better at digging into and debugging client-side code if I was going to be effective. I spent a lot of time pairing and practicing patterns that more experienced engineers were using and eventually working in this space became second-nature.
✓ Effective client-side debugging
Another aspect of the work which was established early-on is documentation. In previous roles I’d updated existing docs or written guides for small chores. Now, I was responsible for documenting entire modules in a way that would be clear and accessible to a large team of engineers at varying levels. We practiced readme-driven development and readme changes were reviewed as scrupulously as code ones and revised often. Explaining my code as I was writing it was eye-opening. Difficult to parse methods and bad variable names had nowhere to hide. I started to get a sense of how high-quality documentation and high-quality code were linked and to pull this thinking into my broader work. When making choices in my code, I developed a clearer awareness of how they would be read by someone unfamiliar with the codebase.
✓ Readme-driven development
✓ Considering how code will be perceived
The project also presented challenges that we hadn’t predicted. Some legacy tools had to be deprecated before we could migrate certain apps and I found myself working through some of our older codebases to modernise the tooling and create a clean slate pre-migration. A lot of this work was on our Front Page app and by its nature was difficult to test. I needed to minimise the risk associated with making big changes in a high-profile environment. I started with the standard advice of splitting the work into smaller tasks and then ordered them in terms of complexity. I built some new relationships with our editorial stakeholders and kept them in the loop. I also worked closely with our in-hours support team to communicate the work’s progress and monitor each release as it was merged.
As it turns out, I did miss something during one of these releases but thanks to the comms and monitoring we had in place it was caught quickly. The change was rolled back within a few minutes and fixed in a local environment. This let me add another new experience to the list; breaking something important in production and working through an incident review process afterwards.
✓ Mitigating risk when making big changes
✓ Communicating progress to stakeholders
✓ Recovering after breaking something important
Once the first version of Page Kit was ready, we started migrating our services off n-ui. We brought some more engineers on board and they were eager to get stuck in! This presented yet another chance to do something brand new; the new team needed to know more about the migrations process and we needed to help them. Along with the tech lead, I broke down all of the work that went into migrating an app and wrote a migration guide that we could all follow as we transitioned our user-facing apps to Page Kit.
This initial piece of knowledge-sharing was a turning point of sorts and we had to do a lot more communicating about our code and the project after this. When I knew of a better way of solving a problem, I had to figure out how to request changes from more senior engineers in the team and explain my reasoning. When newer team members struggled with difficult tasks, I was faced with learning how to support them. I’ve relied heavily on these skills ever since.
✓ Writing a migration guide
✓ Requesting code changes
✓ Supporting newer team members
During the migrations, I spent time pairing with teams who owned the code I was migrating to make sure they were confident with our work and in a good position to support their projects post-migration. I was asked a lot of questions about how the project worked and about how different pieces fit together. The questions tested my understanding of the project as a whole but I was able to practice sharing technical knowledge with different audiences until I knew I could do it in a way that would get them excited about what we’d built.
✓ Sharing knowledge about new tools
This large-scale migration project gave me hands on experience of how all the parts of our frontend fit together in a way that very few projects would have and has been an opportunity to learn and practice a much wider set of skills than I’d anticipated. I’ve gained confidence in our tooling, developed the ability to debug in a new problem space and unlocked a lot of skills that have helped me level up as an engineer.
✓ Achievement unlocked: Migrating to Page Kit
If you like the sound how we work at FT, check out our Product and Technology microsite to learn more about our teams.
