Guide
GitHub generated release notes: make them readable for users
What GitHub gives you by default
The Generate release notes button on a new GitHub release produces a list of merged pull requests along with the contributors and a link to the full changelog. That list is a good record for developers. For the people who use your product it reads like a commit log, because every refactor, test fix and dependency bump sits next to the feature they were waiting for.
Maintainers keep opening issues about this exact gap. Recent ones ask for release notes grouped by label with breaking changes in their own section, ask to keep merge commits and internal work out, and ask for a user-facing changelog in the app instead of pull request titles.
Group and filter with .github/release.yml
GitHub reads a file at .github/release.yml in your repository when it generates notes. You can exclude pull requests by label or by author, and you can sort the rest into categories by label. A category with the label "*" catches anything that did not match an earlier one.
.github/release.yml
# .github/release.yml
changelog:
exclude:
labels:
- internal
- skip-release-notes
authors:
- dependabot
- renovate
categories:
- title: Breaking changes
labels:
- breaking-change
- title: New features
labels:
- enhancement
- feature
- title: Fixes
labels:
- bug
- title: Other changes
labels:
- "*"
This only works as well as your labels do, so add the labels to your pull request template or make a check that fails when a pull request has none. Use the internal label for refactors, tests and tooling, and those pull requests stay out of the notes.
Add two lines a person would write
Generated notes still use pull request titles, and developers write those titles for reviewers. Before you publish, add a short summary at the top of the release that says what changed for a user and whether they need to do anything. A couple of sentences covers most releases, and that summary is what people read.
Publish the notes as a changelog page
Your users don't browse your GitHub releases page. ShipLog turns those releases into a hosted changelog page and an in-app widget, and people who never open GitHub can read them there. You can preview it first with the free GitHub releases to changelog tool, which doesn't ask you to sign up. Paste a public repository and you get every release rendered as a changelog page, and if you then create a free account, ShipLog offers to import them into a project.
Turn my GitHub releases into a changelog
ShipLog is free for up to 10 changelog items. Captain is $9 a month per project.