How to write release notes

To write release notes, list everything that shipped since the last release, group it into new features, improvements, fixes and breaking changes, and describe each change in one or two plain sentences about what the reader can now do. Put breaking changes and required actions first, add the version and date, and publish the notes where your users already look.

The easiest way to write release notes is to start from a draft generated from your merged pull requests, then edit it, instead of starting from a blank page. The steps below work whether you write every word yourself or review a generated draft.

Step 1: Collect what shipped

Start from the source of truth, not from memory. On GitHub that is the list of pull requests merged since the previous release or Git tag. The compare view between two tags shows every commit, and GitHub auto-generated release notes list the merged PRs for you when you draft a release. Write down anything that shipped outside a PR too, such as a configuration change or a pricing update.

Step 2: Decide who will read the notes

Developers who depend on your API or package want precise changes, version numbers and migration steps. Customers, product managers, support and sales want to know what is new and whether it affects them. If you have both audiences, keep a developer changelog in CHANGELOG.md or GitHub Releases and a separate product changelog in plain language. Trying to serve both in one list usually serves neither.

Step 3: Group changes by type

Readers scan release notes, so sections help. A short, stable set works best:

• Breaking changes: anything that needs action from the reader.
• New features: things users can do now that they could not do before.
• Improvements: existing features that are faster, clearer or easier to use.
• Fixes: bugs that are resolved.
• Security: security fixes and changes to how data is handled.

If your team labels pull requests with feature, bug or breaking-change, the grouping is already done. Leave out internal changes such as refactors, CI updates and dependency bumps unless they change behavior.

Step 4: Write each entry for the reader

A pull request title is written for the reviewer. A release note is written for the person using the product. Lead with the outcome, use the words your users use, and keep implementation details out unless the reader needs them.

A good entry has a short title, one sentence on what changed and why it matters, and an optional link to docs or a screenshot for bigger features. Most entries should fit in two lines.

Step 5: Call out breaking changes and required actions

If a change can break someone's workflow or integration, put it at the top, say exactly what changed, and list the steps to adapt. Include the version or date from which the old behavior stops working. This is the one part of release notes where more detail is better.

Step 6: Add the version, date and links

Give every release a version number or date so readers can tell which notes apply to them. If you use semantic versioning, the version itself signals the size of the change: a major version for breaking changes, a minor version for new features and a patch for fixes. Link to the docs, the full list of changes or the GitHub release for readers who want more.

Step 7: Publish where readers already look

Release notes only help if people see them. Developer notes belong in GitHub Releases and CHANGELOG.md. Product notes belong on a public changelog page, in an in-app widget, in an RSS feed or in an email for larger releases. Link the latest notes from your docs and support replies.

A release notes template

## Version 2.4.0 (October 20, 2026)

### Breaking changes
- [What changed]. [What the reader needs to do, and by when].

### New features
- **[Short title]**: [What the reader can do now, in one sentence]. [Link to docs]

### Improvements
- **[Short title]**: [What is better, in one sentence].

### Fixes
- Fixed [the problem as the user saw it].

What is the easiest way to write release notes?

Generate the first draft and spend your time editing. GitHub auto-generated release notes give you a list of merged PR titles grouped by label each time you create a release, which is a good starting point for a developer changelog. For plain-language product notes, Engammo, a GitHub App, writes a release note with AI for every merged pull request, using the PR title, description, labels and a trimmed summary of the changed files. Each note gets a short title, a one-sentence description and a few bullets, and is published to a changelog page, a widget, an RSS feed and JSON endpoints.

You still review the result: every Engammo note can be edited, regenerated or hidden, and you can compile all changes between two Git tags into one versioned note. The Free plan covers 1 repository, 15 release notes per month and 10 AI summaries per month. To set up the workflow, read how to automate your changelog from merged PRs, or compare the best tools to generate release notes from GitHub pull requests.

Release notes checklist

• Every change since the last release is covered, or deliberately left out.
• Breaking changes are at the top, with the steps to adapt.
• Each entry says what the reader can now do, not how it was built.
• The release has a version number or date.
• The notes are published where users already look, and linked from your docs.