Changelog Generator

A useful changelog explains impact, not just commits

A changelog generator earns its keep when it turns a wall of commit messages into release notes a human can read. A changelog is the project's memory, and I learned the hard way that a wall of branch names tells you nothing six months later. What you actually want to know is simpler: what changed, should I care, is anything going to bite me after I upgrade? Commit messages are a fine starting point. Thing is, they're written for you, in implementation-speak. A release note flips that around. It groups things by who feels the change and rewrites cryptic one-liners into bullets a person can read. Most of all it drags security, removals and breaking changes out of the pile so they don't vanish between two typo fixes.

Feed it whatever you've got. Rough notes, conventional commits, a product bullet list, doesn't matter. It reads each line and strips the noisy prefixes, builds Keep a Changelog-style markdown, drafts a short summary, then flags it when your version number and your notes seem to disagree before you hit publish. I lean on it for small tools and WordPress plugin updates. SaaS release posts and GitHub releases too. Even the deploy notes nobody outside the team will ever read.

How to choose the right changelog sections

Here's how I split them. Added is brand-new stuff. Changed is something that already worked but now behaves differently. Fixed is bugs. Security gets its own bucket on purpose, because people read those lines differently and an ops team might have to patch in a hurry. The pair that trips folks up is Removed versus Deprecated. Removed means it's gone today. Deprecated means it still works, but you're putting it on notice. And Breaking? That goes up top, loud, before anything else. Someone skims, misses it, and now it's a bad afternoon for both of you.

• Classification reads prefixes like feat, fix, security, docs, change, remove and breaking, then files each line where it belongs.
• Markdown hands you a release note you can actually review. Keep the empty sections or drop them, your call.
• Release summary drafts a short user-facing paragraph plus a title to slap on top.
• SemVer check nudges you when your impact setting and the notes don't line up.
• Release QA nags you about migration notes, security wording, and the duplicate bullets you probably didn't notice.

SemVer and release communication

SemVer is basically a promise about compatibility. Major says "this will break something, read carefully." Minor says "new stuff, but your existing setup is fine." Patch says "bug fixes, upgrade and move on." Your changelog has to back that promise. Tag a release as a patch, then quietly slip in a breaking change, and people stop trusting your version numbers. Once that trust is gone, honestly, I don't think you ever fully win it back, folks just read every release with their guard up. Same story with burying a security fix in the Fixed pile. The one team that needed to act fast scrolls right past it.

Good changelog habits

1. Group by who feels the change, not by the order the commits happened to land.
2. Swap out the internal verb so the bullet says what actually changed for the reader.
3. Merge the duplicates. Toss anything that only matters inside git history.
4. Put breaking changes and migration steps up front, ahead of the routine sections.
5. Keep security lines accurate and specific. Don't dramatize them either, calm beats scary.

Frequently asked questions

Should every commit appear in the changelog?

Please don't. A changelog is a curated list, not a git log with extra steps. Skip the little refactors and the formatting passes. Skip the dependency bumps nobody will ever notice, unless one of them actually shifts something for a user, a maintainer, or the risk of the release. If a line doesn't move the needle for somebody, leave it out.

What is the difference between Changed and Fixed?

Changed means it worked as intended before and now behaves differently, because you chose to alter it. Fixed means it was broken and you set it right. Why does the distinction matter? A Changed line tells someone to double-check that their workflow still does what they expect. A Fixed line just says a headache went away.

Can this replace release review?

No, and I wouldn't want it to. Treat it as the first draft that spares you the tedious part. You still need a real person to check that the wording is accurate, that the migration notes won't strand anyone, that the security language is right, that every bullet earns its place. The tool sorts and cleans. What ships is still on you.

What format should a changelog follow?

Honestly, just pick one and stick with it. Most people land on Keep a Changelog: a block per version, each stamped with a date, and inside it the familiar Added / Changed / Fixed / Removed sections. It reads clean and it is predictable. Inventing your own format mostly just makes upgrades harder to skim later.

What is semantic versioning?

It's the MAJOR.MINOR.PATCH scheme you've seen everywhere. Bump MAJOR when you break compatibility. Bump MINOR when you add features that don't break anything, and PATCH when you're only fixing bugs. The whole point is that someone glances at the number and roughly gauges how nervous to be about upgrading.