Blog · For maintainers

Release notes best practices for open source projects

Q: What should every release note include?

Three sections: (1) what's new (features, improvements); (2) what's fixed (bug fixes); (3) what's breaking (breaking changes, with migration instructions). The breaking changes section is the most important — without it, users don't know they need to update their code.

Q: How long should release notes be?

Short enough to read in 2 minutes. A release with 10 small changes doesn't need 10 paragraphs — group by 'new', 'fixed', 'breaking', and link to the issues for details. A release with one big change can be longer, but the summary should still be 2 minutes.

Q: What's the difference between a CHANGELOG and release notes?

A CHANGELOG is the cumulative history of all changes (a log file). Release notes are the per-version highlights (a user-facing summary). Most projects have both: the CHANGELOG is generated from commit messages (or PR titles), the release notes are a curated subset of the CHANGELOG with context, migration instructions, and shoutouts.

A great release note is one that a new maintainer can read 6 months later and know exactly what to work on next. The format, the tone, the structure, and the cut-a-release checklist.

Published July 13, 2026 · ~4 min read

The 3 sections

What's new — features, improvements
What's fixed — bug fixes
What's breaking — breaking changes with migration instructions

The breaking changes section is the most important — without it, users don't know they need to update their code.

The format

## v1.2.0 (2026-07-13)

**New:**
- Add support for X (#123)
- Improve Y performance by 30% (#124)

**Fixed:**
- Fix memory leak in Z when W is true (#125)

**Breaking:**
- Rename `oldName` to `newName` (#126). Update your code:
  before: `client.oldName("foo")`
  after:  `client.newName("foo")`

The tone

Three things to keep in mind:

Be specific. "Fixed a bug" is useless. "Fixed a memory leak in the WebSocket handler when the connection is closed during a reconnect" is useful.
Link the issues. Every change should have a link to the issue or PR. Future maintainers (and users) need the context.
Thank the contributors. "@contributor fixed this" or "thanks to @contributor for the bug report" is two lines that matter.

The cut-a-release checklist

Before you tag a release:

All tests pass on the main branch.
The version is bumped (semver: MAJOR for breaking, MINOR for new, PATCH for fixes).
The CHANGELOG is updated.
The release notes are written (curated from the CHANGELOG, with the 3 sections above).
The git tag is created and pushed.
The release is published to the package registry (npm publish, PyPI upload, etc.).
A release announcement is posted (the project's blog, Discord, mailing list, or wherever the community gathers).

Frequently asked questions

What should every release note include?

Three sections: new, fixed, breaking.

How long should release notes be?

Short enough to read in 2 minutes.

What's the difference between a CHANGELOG and release notes?

CHANGELOG is the cumulative log. Release notes are the per-version highlights.

Release notes best practices for open source projects

The format

The tone

The cut-a-release checklist

Frequently asked questions

Related reading

Get rescued projects in your inbox

Related reading on BreakPoint