Guide

Changelog vs release notes: which one does your product need?

People use the two words for the same thing, and for a small team that is mostly fine. There is still a useful difference, and knowing it makes it easier to decide what to write and who it is for.

Changelogs keep the full history

A changelog is the running record of every change to a product, newest first. Each entry has a date or a version and a short line per change. Developers often keep one as a CHANGELOG.md file in the repo, and the Keep a Changelog convention groups entries under headings such as Added, Changed, Fixed and Removed. Its job is to be complete, so someone can look back and see when a thing changed.

Release notes explain one release

Release notes describe one release for the people who use it. They cover the changes a user will notice in plain words, along with any step the user has to take on their side. A good set of release notes leaves out refactors and dependency bumps that nobody outside the team cares about.

Side by side

A changelog answers "what changed and when" for anyone who wants the full history. Release notes answer "what does this release mean for me" for a user who has a minute to spare. Most SaaS products end up with a public page that does a bit of both: a dated list of entries, each written like release notes.

Which one you need

If your users are developers who install a library or a CLI, keep a CHANGELOG.md and publish GitHub releases, because that is where they look. If your users log in to a web app, write release notes for a public changelog page and show new entries inside the app. Most users will never visit a page they have to go looking for. Plenty of teams do both, writing the release notes once and letting the page serve as the history.

How to keep it going

Write the entry when you ship, while the details are fresh, and keep each line to one change a user would notice. Link the docs when a change needs more than a sentence, and put anything that breaks existing behaviour at the top with a date.

Hosting your changelog

ShipLog hosts a public changelog page for your product and adds an in-app widget with a "what's new" badge. Each entry shows up for users while they are inside the app. The free plan holds 10 entries and Captain is $9 a month per project.

Start a free changelog

If you already keep a CHANGELOG.md, the CHANGELOG.md to page tool turns it into a page in one step, and the release notes templates give you a starting point for your next entry.

Ready to write one? Read How to write release notes people read .

If GitHub generates your release notes, read GitHub generated release notes, configured for users to group them by label and leave out bot updates.