Release note categorizer, SemVer check and changelog writer
Writing changelogs is the worst. Right before a release I want to be shipping, not squinting at fifty commit messages wondering which ones a human will ever care about. So I built this to eat the boring half. Paste your raw commits or notes. It sorts them into Added, Changed, Fixed, Security, Removed, Deprecated and Breaking, cleans up the wording for whoever’s reading, spits out release markdown, double-checks your version bump against what you actually wrote, and hands you a short blurb to drop into a release page or a GitHub body. Runs entirely in your browser. Nothing you paste leaves the page.
Paste your real commit notes or issue bullets, then read back what comes out and fix anything that reads wrong. A changelog is supposed to tell the person upgrading what changed for them. It’s not meant to parrot back whatever you typed into git.
A useful changelog explains impact, not just commits
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
- Group by who feels the change, not by the order the commits happened to land.
- Swap out the internal verb so the bullet says what actually changed for the reader.
- Merge the duplicates. Toss anything that only matters inside git history.
- Put breaking changes and migration steps up front, ahead of the routine sections.
- Keep security lines accurate and specific. Don’t dramatize them either, calm beats scary.
Common 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’s 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.
Should a changelog be written for users or developers?
Write it for whoever’s actually going to read it and act on it. Usually that’s the people running your release, not the people who wrote it. So lead with what they’ll notice, the visible effect, in plain words. The internal commit trivia stays where it belongs, in the commits.
