Handover starts on day one

We picture handover as an end-of-project ceremony: a few meetings, a hundred-page document written in a hurry, an archive of repositories. Then the next team discovers that the document describes a system that no longer exists, that CI has been red for four months, and that nobody knows where the certificate expiring on Tuesday lives.

A handover that succeeds is not an event, it is a property of the project, maintained from day one. The guiding question is simple: if the team changed tomorrow, what should have been written down today? Everything that follows flows from that question.

What actually gets handed over

Software is not just its source code. What gets handed over is the ability to operate it, and that ability fits in five inventories:

• the runbook: how to deploy, restore, diagnose the known failure modes, with the exact commands;
• the access map: environments, third-party services, DNS, certificates, and the associated secrets, stored in a vault rather than in someone’s memory;
• the decisions: a log of short, dated architecture decisions explaining the whys the code cannot say;
• the acknowledged debt: the honest list of what is fragile, worked around or temporary, because hidden debt is the kind that costs;
• the calendar: certificate and domain expiries, end-of-support deadlines for major versions, licence renewals.

If one of these inventories does not exist, the handover will discover it at the worst possible moment.

The reproducible environment is the foundation

All the documentation in the world does not replace an environment that rebuilds in one command. Infrastructure described as code, versions pinned by committed lockfiles, development data generated or anonymised, and a CI that stays green: the green CI is the true handover contract, the executable proof that the system is what you say it is.

The most honest test costs half a day: have someone who has never touched the project install it, following only the README. Every question they ask is a hole in the handover, and every hole filled benefits the current team immediately.

Maintenance is a cadence, not a reaction

Maintenance fails when it exists only as a reaction: a publicised vulnerability, an outage, a forced upgrade. It succeeds when it has a rhythm, and the rhythm fits in three levels:

Automation tools (Renovate, Dependabot) open the proposals; CI decides; the team arbitrates. A minor update that waits six months becomes a de facto major one: small steps taken often always beat the big step endured.

Two rules make the cadence sustainable. First, a budget: a recurring window reserved in the schedule, non-negotiable, because maintenance that depends on "time left over" does not exist. Second, an explicit version policy: which components track the latest version, which track long-term support, and until when.

Semver is a convention, not a promise

Semantic versioning states the author’s intent, not your system’s reality. A minor can break a behaviour you depended on without knowing it. Trust comes from elsewhere: tests that cover the project’s real usages, a changelog read before upgrading, and updates in small, isolated, easily reverted batches. That is also why grouped monthly updates work: a reasonable batch, tested together, revertable together.

Measure health, not just activity

Handed-over software must carry its own instruments: a few availability and error indicators that alert humans, the list of end-of-life dependencies, the average age of update lag. Few indicators, but watched. A dashboard nobody opens is a meeting artefact, not an instrument.

The final test: a blank-run key handover

The best verification of a handover happens before it is needed: an exercise where someone outside the project takes a simulated incident from diagnosis to deployed fix, using only what is documented. The exercise costs a day and returns the only information that matters: would the system survive its authors leaving?

The checklist we apply

• Operable runbook: deploy, restore, diagnose, with the commands.
• Accesses and secrets inventoried in a vault, never in a head.
• Architecture decision log kept as you go.
• Debt and workarounds documented without complacency.
• Environment rebuildable in one command, green CI required.
• Maintenance cadence: security in days, minors monthly, majors planned.
• Automated update proposals, human arbitration.
• Expiry calendar: certificates, domains, end-of-support dates.
• Blank-run handover exercise once a year.

Well-handed-over software is not perfect software. It is software about which the next team can say, after one week: "we know where we stand".