ColombiaUS & CanadaSpain

Reference

You have inherited an undocumented system: where to start

Somebody left, or the supplier changed, and now you answer for something you did not write and that cannot stop. The natural reaction is to open the code. Do not start there: start by finding out what can take you down this week.

The day-one inventory

None of this requires understanding the system. They are questions answered by looking, and until they are answered every technical decision is a bet.

Who can reach production
The list of people with access to the server, the database and the cloud console. It usually includes somebody who has left, and that is the first thing to fix.
How it gets deployed
Which command, from where, and who ran it last. If the answer is "it goes up by FTP from someone's laptop", that is not a criticism: it is the fact that orders everything else.
The backups, and the last restore
Whether backups exist is not the question. The question is when somebody last restored one and confirmed the system came up from it. If nobody ever has, you do not know whether you have backups.
The scheduled jobs
The cron entries, the queues and the tasks that only run at month end. They are the biggest surprise, because they are invisible while you read the code and highly visible at three in the morning on the 1st.
Where the secrets are
API keys, credentials, certificates. If they are inside the repository you already know the answer: they have to be rotated, and that becomes urgent rather than important-one-day.
The third-party integrations
What the system talks to and using which credentials: payment gateway, email, messaging, the ERP. Each one is an account somebody pays for and that can lapse without warning.
How much data there actually is
How large the database is and how fast it grows. It decides whether a migration fits in a maintenance window or has to be planned another way.
The versions of everything
Of the language, the framework, the operating system and the database engine. That is the next section, and it is usually where the first deadline comes from.

What is about to expire

An inherited system rarely fails because of its own code. It fails because something underneath stopped receiving patches and nobody was watching. That is the part with a date on it, and somebody else sets the date.

  • The language version. If it is PHP the date is published: the PHP and Symfony support calendar says how long each branch gets patches, and which one requires which.
  • The server's operating system. A distribution out of support stops getting security patches even if your application is untouched.
  • The database engine, which tends to run a couple of versions behind everything else.
  • Abandoned dependencies: the ones with no new release in years. They do not expire on a date, they expire the day a flaw turns up and there is nobody to fix it.

Keep, wrap or replace

With the inventory in front of you, every part of the system lands in one of three places. The decision is not made on how old the code is, but on what each change costs and what happens when it falls over.

  1. Keep

    It works, it changes rarely and its technology is still supported. Leave it. The urge to rewrite this is what consumes budgets.

  2. Wrap

    It works but nobody wants to go in. Put an interface in front of it and build the new work against that, replacing the inside piece by piece. The system never stops.

  3. Replace

    Every change costs out of all proportion, or the technology no longer receives patches. It gets replaced in pieces and each piece goes to production when it is ready: there is never a parallel version waiting to be integrated at the end, which is where these projects get stuck.

What is not on that list is rewriting the whole thing at once. With a system in production that cannot stop, that option does not compete: the business keeps changing while the rewrite runs, and the new version is chasing a target that moves.

Frequently asked questions

The system has no tests. Can it be touched?
Yes, but not by touching it first. Tests get written for the part about to move, even though the rest still has none: they are the net for that specific change. Migrating without a net is what turns a migration into a crisis.
How long does it take to understand an inherited system?
The inventory above is answered in days rather than weeks, and it is enough to decide with. Understanding the whole thing takes as long as it takes and is almost never necessary: you understand the part you are about to touch, and the rest gets documented as you reach it.
There is nobody left who knew it. Does that change things?
It changes the order. With nobody to ask, the running system is the only reliable source: the logs, the database and the behaviour in production tell the truth, and any document that turns up has to be checked against them before it is believed.
Is it worth fixing, or better to start again?
Starting again is the right answer less often than it looks. A system that has been in production for years contains business decisions nobody remembers making and nobody wrote down: rebuilding from a specification loses all of them, and they come back one at a time, as incidents.

Where do we start?

Two ways to begin, depending on what you have in front of you today. Answered within one working day.

Talk to us