Handing over legacy code to a new team

A legacy code handover works when the old and new team overlap for a while, when the new team can build and deploy the code on its own before changing anything, and when the first tasks are small. Documentation helps, but a lot of knowledge lives only in the heads of the people working on the code now. So schedule time with them while they are still around.

Map what is there first

Start with an inventory, before the first handover session. The code itself is usually the easy part. The risk sits in everything outside the repository:

• servers, environments and the pipeline that deploys
• integrations with other systems, and who the contact person is for each
• scheduled jobs, such as a cron job on a server nobody thinks about any more
• domains, certificates and accounts with cloud and SaaS vendors
• secrets, and who knows them
• licences and contracts in the name of the previous party

For each item, note who has access today. You will use the same list later to move that access over.

Plan an overlap with the old team

My advice is a period of a few weeks in which both teams work on the code. Do a walkthrough per component and record it. Then let the new team pick up real tickets while someone from the old team keeps an eye on their work. That brings up the questions nobody thinks of in advance.

Keep one document with open questions, so the old team can answer them when it suits them. If the previous vendor is leaving, put the handover into the agreements about the end of the contract: how many hours, which documents and when access changes hands.

If there is nobody left to ask, the git history, the old tickets and the logs are your sources. That takes longer, and your planning has to allow for it.

What to write down

A handover is the wrong moment to start a big documentation project. Write down what the new team needs to work independently:

• a README that gets the system running locally
• a runbook for deploying and rolling back
• a sketch of the components, the integrations and where the data lives
• a list of known problems and places where you need to be careful
• short notes on earlier decisions, so it is clear why something was built the way it is

Let the new team write these documents and the old team check them. You see straight away whether the knowledge came across, and the documentation is written by the people who will use it.

Change nothing until the new team can run the code

The first goal is that the new team builds the code, runs the tests and deploys to a test environment without help. After that, one small change goes to production through the normal route. Only then do you know the whole chain works.

If error monitoring is missing, set it up first. You want to know what goes wrong before the new team changes anything, so you can see the difference afterwards.

If there are few tests, write characterization tests around the parts you are about to touch. Such a test records what the code does today, even when that is not what it should do. If the behaviour changes by accident later, you see it right away.

The first tasks

For the first weeks, pick low-risk tasks that still go all the way to production: small bug fixes, better logging, adding tests, updating a dependency that comes with a clear changelog. Hold off on large refactors in the first month, because the team does not know the edge cases yet.

Give more context with each ticket than you would for a team that knows the code. How to do that is covered in writing tickets a remote developer understands. For a new developer's first days in general, see onboarding a remote developer.

Risks to cover in advance

Some risks only show up when it is too late, unless you look for them beforehand:

• Knowledge that sits with one person. Have that person do the first walkthrough.
• Secrets the previous party knows. Rotate them right after the handover.
• Accounts in the previous party's name, with the cloud provider, the domain registrar or the app stores. Move them to your own organisation.
• A deployment that only works from one person's laptop. Move that step into the pipeline.
• Outdated dependencies with known vulnerabilities. Make a list and schedule the updates.

Rewriting can wait

A new team often wants to rewrite old code. Work with it for a few months first, because only then do you know which parts really get in the way. If you want to replace it after that, do it step by step: build new parts next to the old system and move functionality across bit by bit. Martin Fowler calls this the strangler fig approach.

That is how we worked at Vision Healthcare. A PHP back end and a .NET Framework Forms front end moved step by step to .NET Core services and a React/Next.js front end, without bringing the business to a halt.

Sources

• Martin Fowler, Strangler Fig Application