Project guides

GitHub release notes template for open source projects

Good release notes tell a user whether to upgrade and what to do next. A list of merged pull requests is useful evidence, but it rarely explains the complete upgrade experience. Add the user impact and any required actions before publishing.

GitHubStart editorial team · Updated

Start with a user-focused template

Replace every bracketed field with verified information. Remove irrelevant sections rather than inventing features. If no upgrade action is required, say that explicitly after checking the supported upgrade path.

# [Version] — [Release date]

## Highlights
- [User-visible improvement and who benefits]

## Upgrade
- From: [supported previous version]
- Action: [required migration or no action required]
- Verify: [how to confirm a successful upgrade]

## Breaking changes
- [Changed behavior, affected users and migration link]

## Fixes
- [Problem resolved and issue or pull request link]

## Known issues
- [Remaining limitation and workaround]

## Contributors
[Credit contributors and link the full changelog]

Turn generated notes into a readable explanation

GitHub can generate notes containing merged pull requests, contributors and a full changelog link. Treat that output as a draft. Check the release boundary, remove irrelevant entries and group changes by the tasks your users perform.

For example, “Fix parser edge case” gives little guidance. If accurate, explain that CSV files with an empty final column now import correctly, and link the fix for technical details. Do not claim every parsing issue is solved when only one case changed.

Review the upgrade path before announcing

Try the documented upgrade from a supported previous version. Check download links and ensure documentation matches the release. Distinguish a preview from a stable release and make remaining limitations easy to find.

Publish the release information before linking to it from a community post. Use the announcement to highlight one meaningful improvement, while the release notes remain the detailed reference. Capture follow-up questions and clarify instructions when needed.

Common questions

Are release notes the same as a changelog?

They overlap. A changelog records changes over time; release notes explain a particular release and its effect on users. Link them so readers can move between the overview and details.

Can I publish automatically generated notes unchanged?

Review them first. Generated pull request titles may omit migration steps, user impact or known issues.

Should every small code change appear in the highlights?

No. Use highlights for changes that matter to users and keep detailed technical history in the linked changelog.

References