What turned up when we searched old repositories for keys.

What we would do differently

Writing it down was the last step and possibly the most useful one. A short note about what we tried, what failed and why we stopped has saved us more time than any tool. When this comes up again, and it will, someone will search the repository, find these paragraphs and skip the whole expensive afternoon.

We started by reading the code rather than the documentation, because the code is what runs. Most of the surprises in a WordPress project live in the gap between what a function promises and what the theme actually asks of it. An hour with the templates open told us more than a week of status meetings ever had, and it gave us a list of real questions to bring to the client.

The boring fix

The first measurement is always the most useful one, even when it is rough. Write down the query count, the page weight and the time to first byte before you change anything. Without those numbers you cannot tell an improvement from a coincidence, and three weeks later nobody will remember what the site felt like before you touched it.

Caching hides problems as often as it solves them. A page that is fast only when the cache is warm is a page that falls over on the morning after a release, which is exactly when people are looking at it. Test the cold path on purpose. Clear everything, load the home page once, and read what the database had to do.

Where it breaks

Nothing here needed a new plugin. The fix was a small change to a query and a better idea of when to run it. That is usually the case: the expensive part of a site is rarely the code you can see, and adding a layer on top only moves the cost somewhere harder to find. Delete first, then decide what is still missing.

Escaping belongs at the point of output, where a reviewer can see it. When a value has been cleaned three functions earlier, nobody can tell by reading the template whether it is safe, and the next person to touch that line will not know either. We moved every escape next to its echo and the file got shorter and easier to trust.

What to check next

The review took longer than the fix, and that is the right way round. Most of the time went on working out what the code was meant to do and who depended on it. Once that was written down, the change itself was four lines, a test and a note in the changelog that future maintainers will actually thank us for.

A throwaway site is the cheapest tool in the kit. We can build one in a minute, break it completely and delete it without a single awkward conversation. Everything risky in this post happened there first, including the mistakes we are not going to mention, and nothing touched production until it had survived a full run from a clean start.

The short version

Releases go badly when they are exciting. Our best ones are dull: a checklist, a backup someone has actually restored, a rollback plan and a time of day when the people who can fix things are awake. If your release needs courage, something earlier in the process needs more attention, and a calmer Tuesday afternoon will show you what it is.