Building the Changelog — Docs From Git Archaeology
Built this changelog itself: a Keystatic-managed content collection with topic-based entries, a /changelog.md export for AI agents, a dedicated changelog.xml sitemap — with entry dates verified against the actual git history.
The idea
Most changelogs are chronological commit noise. This one is organized by topic — each entry covers one system (crawl pipeline, bot classification, RUM) with the decisions, tradeoffs, and context that a commit log can’t carry. The inspiration was build-log posts like Suganthan’s “How I built this site,” but structured as a maintained collection rather than a one-off post.
How it’s built
- Astro content collection — schema: title, date, category, summary, draft. Categories: foundation, crawl, edge, performance, content, identity, ai, polish.
- Keystatic collection — entries are editable from the CMS like blog posts and notes. Adding an entry is a form, not a code change.
/changelog/— index page with color-coded category badges and one-line summaries./changelog/[slug]/— full entry pages with rendered markdown./changelog.md— the whole changelog as one plain-markdown document, grouped by category with a table of contents. Built for AI agents; a browser gets it as a downloadable file./changelog.xml— dedicated XML sitemap listing the changelog index and every published entry, submitted to Google Search Console separately from the main sitemap so changelog indexation can be monitored in isolation.
Git archaeology — the dates were wrong
The first draft of these entries carried estimated dates spread across 2025. Overlaying them with git log showed the truth: the entire site was built in 13 days — June 25 to July 7, 2026 — across 102 commits and 58 pull requests. Every entry date was corrected to the day its work actually landed on main.
The overlay also surfaced things the polished narrative had smoothed over:
- Day 1 took six attempts (three “force” commits and a revert) just to make the Cloudflare adapter deploy — the fix was configuration, not code
- CWV capture landed on day 3, five days before any dashboard existed to show it — instrument first, visualize later
- The blogroll’s fetch-on-every-request mistake was caught and converted to build-time prerendering the same day it shipped
- Owner-traffic tagging didn’t exist until day 10 — ten days of my own AI-agent traffic polluting the crawl stats
The AI-readable summary field
Each entry’s summary is written as a single self-contained sentence — who/what/how — so that an agent reading /changelog.md or the index page gets usable facts without parsing the full body. Same philosophy as the entity map’s hasChunks: pre-digest the content for machine consumers instead of making them infer.
What’s next
The backlog lives here too: future work is drafted as unpublished changelog entries (draft: true), so the roadmap and the history share one system. When a backlog item ships, its draft flips to published with the real date — the entry that described the plan becomes the entry that documents the work.