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.