What are release notes, and how do they differ from a changelog?
Release notes are a written summary of what a specific release contains, published when that release ships. A changelog is the running list of those releases over time. Release notes describe one version in depth; a changelog is the archive readers scroll through.
Release notes vs changelog
The difference is scope and shape, not subject. Release notes are tied to a version or a date range and often include context, screenshots, upgrade steps, and known issues. A changelog is the chronological index of entries, optimized for scanning rather than reading.
In practice most teams write release notes and publish them as changelog entries, so the changelog becomes the archive of every set of release notes they have written.
What good release notes contain
State the user-visible outcome first, then the detail. Group related changes so a reader sees one coherent story rather than fifteen commits. Call out anything that requires action: breaking changes, deprecations, migrations, or new settings that default to off.
Write a version for each audience that needs one. Customers need the outcome; support needs the edge cases and the workaround; sales needs the sentence they can say on a call.
Who writes them
Release notes are usually written by product marketing, a product manager, or the engineer who shipped the change. Because the raw material lives in commits, pull requests, and issue trackers, teams increasingly draft them with an AI agent that reads that history and then have a human review the draft before it publishes.
