My Own Site Inventory Was Wrong in Four Places

If you are about to migrate a site, do not start from your inventory of it. Start by fetching every URL it serves and comparing that against what you believed. I had a careful written inventory of this site. It was wrong in four places, and every one of them would have shipped.

What I thought was here

Ten blog posts, two of them recent and eight of them travel-blog inventory from 2017 to 2020. One page each for home, blog, about, contact and projects. A privacy policy and an imprint. Two posts sharing a title, which I had written down as a duplicate to consolidate with a redirect.

That inventory came from looking at the site. It was not lazy. It was made the way these normally are, by reading the admin and clicking around the front end.

What was actually here

Thirteen posts, not ten. The blog index paginates at ten. I had counted a page.

The duplicate was not a duplicate. Two posts really do carry the title “Why You Should Always Be Grateful”. The second one is a completely different piece about filling time when you are home alone, and its slug says so. At some point the wrong title got pasted onto it and stayed there for six years. Consolidating them with a redirect, which is what my plan said to do, would have deleted a post.

Every image in every legacy post was already gone. Twenty-three files, all returning 404, none present in the media library. Those posts have been rendering with broken images to real visitors for years and I did not know, because I had not opened one of my own 2017 posts in a long time. The migration did not lose them. They were lost before it started.

Projects was not a page. It was a custom post type with an archive and nine written entries, about nine thousand words. My plan had it as a single hand-authored page, which would have thrown away nine URLs and everything on them.

Why the difference

An inventory made by looking is an inventory of what renders. It cannot see a 404 on an image you do not scroll to, a title that has been wrong so long it looks normal, or a count cut off by pagination.

What found all four was boring: fetch the sitemap, fetch every URL in it, fetch every image referenced in every post, and diff the result against the document. Thirty-five URLs. It took a few minutes and it changed the plan four times.

What I do differently now

Two rules, both cheap.

Fetch, do not look. Before any migration, pull the real inventory over HTTP and treat the written one as a hypothesis. If the two disagree, the site is right.

Make the parity a test, not a promise. The list of every URL the old site served is now a file in the repo, and a build step fails if any of them is neither built nor redirected. The claim “every address still works” is checked on every build instead of being something I remember to verify once.

The second one matters more than it sounds. The first check is a thing you do when you are paying attention. The second is a thing that keeps being true after you stop.