A Year of Release Notes From the Software Nobody Brags About
Photo: Secondarywaltz, Public domain, via Wikimedia Commons
Sometime last January, on a whim that I can only describe as occupational hazard, I subscribed to the release feeds of five tools I use every single day: 1Password, a popular open-source PDF reader, a terminal emulator, a note-taking app, and SQLite (which, to be fair, publishes some of the best release notes in the business). The deal I made with myself was simple — every time a new version shipped, I'd read the full changelog before updating. No skimming.
Twelve months and roughly 140 releases later, I have opinions.
What I Actually Read
Let's set expectations. If you're imagining juicy feature announcements, you're imagining the wrong genre. Across the year, I'd estimate the breakdown of changelog entries looked something like this:
- Bug fixes: ~55%. The overwhelming bulk of maintenance is just... fixing things that broke.
- Dependency and platform updates: ~15%. Bumping library versions, chasing OS releases, keeping certificates current.
- Security patches: ~8%. Usually terse, occasionally alarming in their brevity.
- Deprecations: ~7%. The slow, polite farewell tour of old APIs.
- Actual new features: ~15%. And most of those were small.
Read that list again, because it's the most honest org chart in software. The majority of engineering effort on mature, beloved tools is invisible upkeep. Nobody demos a CVE patch on a conference stage.
Pattern One: The Deprecation Dance
My favorite recurring drama was what I came to call the deprecation dance. It goes like this: a feature is marked deprecated in release X, with a note saying it'll be removed 'in a future version.' It is then not removed for anywhere between eight months and — in one case I tracked — over three years. Meanwhile the changelog logs a gentle escalating series of nudges: warnings added, warnings made louder, docs updated, a migration guide published, and finally, quietly, a line like 'Removed legacy export format.'
The best maintainers treat removal like a diplomatic negotiation. The worst just delete things. One of my five tools shipped a breaking change to its config file format with a changelog entry that read, in full, 'Updated configuration handling.' I lost an afternoon to that sentence. I've forgiven them, mostly.
Pattern Two: Silent Breaking Changes
Which brings me to the pattern that should make you slightly nervous. Roughly a dozen times this year, behavior changed in a way that wasn't flagged as breaking — no deprecation notice, just a fix that happened to alter behavior someone (me) depended on. A PDF reader changed its default handling of malformed documents. A note app changed how it sorted search results, which silently broke a workflow I'd built around the old order.
Here's the thing: from the maintainer's perspective, these are all correct decisions. The old behavior was a bug. But 'we fixed a bug' and 'we broke your setup' are the same commit wearing different name tags, and the changelog is where you find out which one you got.
Pattern Three: The Long Tail Is Very Long
The single most humbling statistic from my notes: multiple tools fixed bugs that were a decade old or older. SQLite closed tickets originating in the early 2010s. My terminal emulator fixed a rendering glitch first reported in an issue from before I owned my current laptop. There's a version of software maintenance that's less like gardening and more like geology — old strata of decisions surfacing years later, and someone patient enough to excavate them.
Why I Think Changelogs Are the Most Honest Docs We Have
Marketing pages tell you what software wants to be. Documentation tells you what software is supposed to be. Changelogs tell you what software is — the unedited ledger of what actually changed, written by the people who changed it, usually within hours of shipping.
They're also a masterclass in how to write for engineers under time pressure. The best ones (SQLite, again, is exemplary) tell you the what, the why, and the blast radius in three lines. The worst ones tell you nothing and cost you a Saturday.
The Habit I'm Keeping
I'm not going to pretend reading release notes is a thrilling hobby. But it's become a genuine professional edge in three concrete ways:
- I update with fewer surprises. I know which versions to skip and which config options to migrate before they vanish.
- I write better changelogs myself. Reading hundreds of them calibrates your sense of what a useful entry looks like — and what a useless one costs the reader.
- I've internalized what maintenance really looks like. My estimates for 'small fixes' got more realistic once I'd watched a year of them accumulate in other people's projects.
The tools we lean on daily aren't maintained by magic. They're maintained by an unglamorous, endless stream of small fixes, careful removals, and the occasional silent behavior change — all recorded in plain text for anyone patient enough to read. Spend a month with a changelog feed or two. It's the closest thing our industry has to an honesty requirement.