Recovering an upgrade path from two years of undocumented customisation

The challenge

The firm ran its operations on a commercial platform it had bought years earlier and then modified — reasonably, and repeatedly — to fit how it actually worked. The modifications had been made directly in the vendor's source.

By the time we were asked to look, the installed version was several major releases behind. Each new vendor release widened the gap, and the pending releases included security fixes the firm could not apply.

The position was uncomfortable in a familiar way: the system worked, nobody wanted to touch it, and doing nothing was getting more expensive every quarter.

The engineering problem

To merge customisations forward, you need to know what they are. There was no record. Changes had been made over about two years by several people, without version control on the vendor code, and without documentation.

So the first problem was archaeology, not merging: reconstruct the diff between the vendor's original release and the running system, and then classify every difference. Deliberate customisation, incidental change, abandoned experiment, or vendor patch already superseded upstream.

There was a trap in this, and we walked into part of it early. An archive on the server that looked like a pristine copy of the original version turned out not to be one — it had itself been modified. Building the merge on that baseline would have silently discarded real customisations and reintroduced changes that had been deliberately removed. We caught it by verifying the archive against the vendor's actual distribution rather than trusting its name.

The approach

We worked in four passes.

First, establish a verified baseline: obtain the vendor's genuine original release, confirm it by checksum, and put both it and the running system under version control.

Second, produce the complete diff and classify every hunk, with the client's team confirming intent where the code could not tell us. This is where most of the value was created, because it converted tacit knowledge into a written record for the first time.

Third, replay the customisations onto the current vendor release as a reviewable merge — one logical change at a time, each with a note explaining what it does and why it exists. Several turned out to be unnecessary, because the vendor had implemented the same capability upstream.

Fourth, re-implement what could be re-implemented through the platform's supported extension points rather than in its core, so the next upgrade is smaller than this one.

The solution

The delivered result was the upgraded platform, but the durable deliverable was the record: a classified inventory of every customisation, why it exists, whether it is still needed, and whether it now lives in core or in an extension.

The upgrade itself was run against a copy with the firm's real data, with a documented rollback, before it went anywhere near production.

Technology

• Checksum-verified vendor baselines
• Automated diffing with manual classification of every change
• Reviewable, one-change-at-a-time merge with written rationale
• Migration of customisations to supported extension points where possible
• Rehearsed upgrade against production-like data with a documented rollback

Business value

The platform is supportable again, and security releases can be applied. The larger change is structural: the customisations that remain are documented and, where possible, no longer in the vendor's code — so the firm is not rebuilding this position from scratch in three years.

Key learnings

Verify the baseline before trusting it. This nearly cost the project its correctness, and it is the finding we would most want another team to take from this write-up.

Classification is the deliverable. The merge was mechanical once we knew what each change was for. Everything hard was in finding out.

Some customisations are already dead. Several existed to work around behaviour the vendor had since fixed. An upgrade is a rare, legitimate opportunity to delete code, and it is worth taking.