What should good release notes include?

Strong release notes cover the version and date, a short summary, then grouped sections for new features, bug fixes, and known issues. Adding deprecations and upgrade notes helps users avoid surprises when they update.

What is semantic versioning?

Semantic versioning (semver) uses MAJOR.MINOR.PATCH, like 2.4.1. You bump MAJOR for breaking changes, MINOR for backward-compatible features, and PATCH for backward-compatible bug fixes. The tool flags versions that do not match this format.

Should I write release notes for users or developers?

Write for whoever consumes the product. User-facing apps need plain-language notes focused on what changed for the user; libraries and APIs can be more technical and should always call out breaking changes and migration steps.

What is the difference between deprecations and breaking changes?

A deprecation warns that a feature will be removed in a future release but still works now, giving users time to migrate. A breaking change has already removed or changed behavior — those belong in upgrade notes and usually trigger a MAJOR version bump.

Markdown or plain text — which should I use?

Use Markdown for GitHub releases, changelogs, and docs sites that render it. Use plain text for in-app update dialogs, email, or anywhere Markdown will not be rendered. The tool produces both from the same input.

Software Release Notes Builder

Email me this result

Get this tool's output sent to your inbox, plus one useful tool a week. No spam, unsubscribe any time.

Release notes people actually read

Most release notes are either a wall of commit messages or a single vague line that says “bug fixes and improvements.” Good notes sit in between: grouped, scannable, and written for the person on the other side of the update. This builder takes your raw list of changes and formats them into clean release notes following the widely used “Keep a Changelog” structure — in Markdown or plain text.

How it works

You enter the version and date, then drop your changes into labeled buckets: new features, improvements, bug fixes, deprecations, known issues, and upgrade notes. The tool renders each non-empty section with a heading and bullet list, skipping any section you leave blank so the output stays tight.

It also validates the version against semantic versioning (MAJOR.MINOR.PATCH). If you type something that is not valid semver — like v2 or 2.4 — it flags it, because consistent version numbers are what let users and tools reason about the size of a change.

Tips and example

Lead each bullet with what changed for the user, not the implementation detail. “Projects now load 2× faster” beats “Refactored the project loader.”
Always surface known issues — users trust a changelog that admits what is still broken far more than one that pretends everything is perfect.
Put migration steps in upgrade notes, e.g. Run \acme migrate` after upgrading`. Anything a user must do belongs here, not buried in features.
Bump the version correctly: a breaking change is a MAJOR bump even if it feels small.