A release notes template you can steal

Start here

The template

Four sections, in the order readers care about them. Most releases only need two. Empty sections get deleted, not left as sad little headings.

## 1.4.0 (2026-08-20)

One sentence on the theme of this release, if it has one. Delete this line if it doesn't.

### New
- The feature, described as what a user can now do. Not the branch name.

### Improved
- The thing that got better, with the old behavior named so the change means something.

### Fixed
- The bug, described as the symptom people actually saw. The internal cause is for the PR.

### Breaking
- What breaks, who it affects, and the one-line migration. If this section is empty, delete it.

The rule doing the work here: every line describes what a user can see, do, or stop worrying about. If a line only makes sense to someone with repo access, it belongs in the PR description, and it already lives there.

Variant one

GitHub releases

GitHub’s “Generate release notes” button gives you a list of merged PR titles with usernames. That’s an ingredient list, not a meal. I use it as raw material: paste it under the template above, rewrite each line as the user-visible change, and keep the PR links because they are the receipts.

A .github/release.yml at least sorts the raw list into sections for you before you start rewriting:

# .github/release.yml
changelog:
  categories:
    - title: New
      labels: [feature]
    - title: Fixed
      labels: [bug]
    - title: Maintenance
      labels: [chore, dependencies]
  exclude:
    labels: [skip-changelog]

The skip-changelog label matters more than the categories. Dependency bumps and CI fiddling are most of my merges some weeks, and nobody subscribed to hear about them.

Variant two

A changelog template for CHANGELOG.md

If the file lives in the repo, use the Keep a Changelog shape. It’s the closest thing this niche has to a standard, tooling understands it, and future you can diff two versions without archaeology.

# Changelog

All notable changes to this project are documented here.
Format follows Keep a Changelog; versions follow semver.

## [Unreleased]

## [1.4.0] - 2026-08-20
### Added
- The new thing, one line, user-visible.

### Changed
- The behavior that changed, and what it was before.

### Fixed
- The symptom that no longer happens.

[Unreleased]: https://github.com/you/repo/compare/v1.4.0...HEAD
[1.4.0]: https://github.com/you/repo/compare/v1.3.0...v1.4.0

The Unreleased section is the trick that makes the file sustainable: you add a line when you merge, not in a heroic session the night before a release. More on the conventions in the changelog format guide.

Variant three

Word, Google Docs and Confluence

I spent years in enterprise software, so I know this document. It goes to people who will never open the repo, which changes what goes in it. Same base template, wrapped in context a stakeholder needs:

• Title, product name, version, release date. On one line, at the top.
• A two-sentence summary a manager can paste into their own update.
• What’s new, improved and fixed, from the base template.
• Known issues, with a workaround for each or an honest “none”.
• Who to contact when something in this list breaks anyway.

That outline pastes straight into Word, Google Docs or a Confluence page. The formats differ, the structure doesn’t, and asking a template site for a .docx download when you have a working copy of Word is a scam I refuse to participate in.

The hard part

Filling it in

A few rules that survived contact with my own releases. Describe the symptom, not the cause: “fixed the login loop on Safari” beats “corrected token refresh race”. Pick one tense and stay in it. Name the old behavior when something changes, because “improved search” tells nobody anything. And cut any line a user can’t act on or feel.

Full disclosure on how this page gets practiced: I don’t write mine by hand anymore. I built Merge & Tell because I had years of merged PRs and a changelog I updated roughly never. It drafts the entry from the merged PR, I edit the draft, and the result is the updates page on this site. I use it every day, mostly so I can’t chicken out of telling anyone what I shipped.

Honesty

What a template won’t fix

A template fixes the blank page. It does not fix cadence, which is the real reason most changelogs die: writing the entry is a decision you have to make every single release, forever. It also won’t tell you what to leave out, and leaving things out is most of the job. If your last entry is from eight months ago, the problem was never the formatting.