What should a release notes template include?

At minimum: a version number or date, changes grouped by type (new, improved, fixed), and one plain-English line per change written for the reader rather than the author. Customer-facing notes should add where to find each feature and a way to reply. API changelogs should put breaking changes first, each with a migration step and an effective date.

What is the difference between release notes and a changelog?

A changelog is the complete, chronological record of every notable change, usually terse and aimed at developers (the Keep a Changelog format is the standard). Release notes are a curated announcement for one release, written for users, with the headline change explained properly. Most teams keep both, generated from the same underlying list of merged pull requests.

How often should we publish release notes?

Match your release cadence. Teams that deploy continuously usually batch changes into a weekly note, because per-deploy notes become noise. The one rule: do not go silent. A changelog that stops updating reads as an abandoned product, and a one-line entry beats a gap.

Should release notes be written for users or developers?

Both, in separate documents. Customer-facing notes describe what the reader can now do, with no PR numbers or jargon. Internal notes keep the PR numbers, owners, feature flags, and follow-ups. API changelogs are a third audience with their own rules (breaking changes first). Trying to serve all three in one document is how release notes end up serving nobody.

How long should app store release notes be?

Aim for under 500 characters, which is the Play Store limit and comfortably fits the roughly three lines the App Store shows before truncating. Put the single best change in the first line, and never publish only "bug fixes and improvements": name at least one real change.

Can release notes be generated automatically from GitHub?

Yes. GitHub can auto-generate a list of merged PR titles per release, which works as a raw changelog but reads like one. GitLoom goes a step further: it reads your merged pull requests and commits, writes plain-English release notes, deduplicated and ready to forward, and delivers them to Slack, email, or Telegram. Each report accepts custom instructions so the notes match your house style. If nothing shipped, it stays quiet. Setup takes about two minutes.

Resources · Templates

Release notes and changelog templates you can copy

GitLoom is a Slack-first pull request notification tool that watches your GitHub repos and turns merged work into plain-English release notes, weekly digests, and stuck-PR alerts.

You do not need GitLoom to use this page. Below are ten copyable release notes and changelog templates, each with realistic example content and guidance on when it fits. Free, no signup.

The gallery

Ten templates, from CHANGELOG.md to the App Store

Every template below is filled in with realistic example content so you can see how it reads, not just how it is structured. Copy one, replace the examples with your own changes, and delete what you do not need.

Keep a Changelog (CHANGELOG.md)

Markdown

Best for: Open source projects and versioned libraries

The de facto standard changelog template. A single CHANGELOG.md at the repo root, newest release first, changes grouped into six fixed categories.

Template

# Changelog

All notable changes to this project are documented in this file.

The format follows Keep a Changelog (keepachangelog.com), and this
project adheres to Semantic Versioning (semver.org).

## [Unreleased]

### Added
- Work that has merged but is not yet in a tagged release.

## [2.4.0] - 2026-07-10

### Added
- Bulk invite: import teammates from a CSV file.

### Changed
- Search results now reflect edits within seconds.

### Deprecated
- The v1 export endpoint. It will be removed in 3.0.0.

### Fixed
- Webhook deliveries that timed out are now retried instead of
  being dropped.

### Security
- Upgraded the session library to patch CVE-2026-1234.

## [2.3.1] - 2026-06-28

### Fixed
- Invite screen no longer shows placeholder copy for empty teams.

[Unreleased]: https://github.com/org/repo/compare/v2.4.0...HEAD
[2.4.0]: https://github.com/org/repo/compare/v2.3.1...v2.4.0
[2.3.1]: https://github.com/org/repo/compare/v2.3.0...v2.3.1

How to use it well

Keep an Unreleased section at the top so merged-but-unshipped work has a home and release day is a rename, not archaeology.
Stick to the six standard categories (Added, Changed, Deprecated, Removed, Fixed, Security) and delete the ones a release does not use.
Write one line per change for humans. A changelog is not a copy of git log; squash-merge noise does not belong here.
Use YYYY-MM-DD dates and link each version heading to a compare view so readers can see the actual diff.

Minimal changelog

Markdown

Best for: Small products that want a changelog page without ceremony

Three labels, one line per change. The lowest-maintenance changelog template that still reads well on a public /changelog page.

Template

# Changelog

## 1.8.0 (July 10, 2026)

- New: bulk invite teammates from a CSV file
- Improved: search results update within seconds of an edit
- Fixed: timed-out webhook deliveries are retried, not dropped

## 1.7.2 (June 28, 2026)

- Fixed: invite screen showed placeholder text for empty teams

## 1.7.1 (June 21, 2026)

- Improved: invoice PDFs load about twice as fast

How to use it well

Three labels are enough: New, Improved, Fixed. Resist adding more categories until you genuinely need them.
Publish even one-line releases. A changelog with gaps reads as an abandoned product.
Start each line with what changed for the reader, not with the internal ticket number.

SaaS customer-facing release notes

Markdown

Best for: Product announcements to paying customers

A curated announcement for one release: a headline feature explained properly, then improvements and fixes as short lists. Works as an email, a blog post, or an in-app note.

Template

# [Product] release notes: July 10, 2026

## New: bulk invite from CSV

Getting a whole team on board used to mean sending invites one by
one. You can now upload a CSV, review the list, and invite everyone
in one click. Duplicates and existing members are skipped
automatically.

Find it under Settings > Team > Invite.

## Improvements

- Search results now reflect edits within seconds, not minutes.
- Invoice PDFs load about twice as fast.

## Fixes

- Timed-out webhook deliveries are now retried automatically.
- The invite screen no longer shows placeholder text for teams
  with no pending invites.

Questions or feedback? Reply to this email or write to
[email protected].

How to use it well

Lead with one feature and explain it in two or three sentences: the old pain, the new behavior, where to find it.
Write in second person ("you can now"), not first person ("we shipped"). Customers care about what they can do, not what you did.
Cut anything customers cannot see. Internal refactors belong in the internal notes, not here.
End with a way to reply. Release notes are one of the few emails customers actually read.

Internal release notes

Slack message

Best for: Telling your own team what shipped, in Slack or email

The unpolished twin of customer release notes: PR numbers and owners included, flags and follow-ups called out, nothing hidden.

Template

Shipped this week (July 6 to 10)

*New*
- Bulk CSV invite (web#512, Priya). Behind the team-invites flag
  until Monday.
- Rate limiting on webhook delivery (api#482, Marcus).

*Fixed*
- Timed-out webhooks now retry (api#505, Ale). Keep an eye on
  retry queue depth this week.
- Empty-state copy on the invite screen (web#508, Tom).

*Heads up*
- The v1 export endpoint is deprecated. Migrate internal callers
  by August 1.
- Billing migration lands behind a flag next week.

Full diff: v2.3.1...v2.4.0

How to use it well

Include PR numbers and owners. Internal notes double as a "who do I ask about this" index.
The Heads up section is the most valuable part: flags flipping, deprecations, things to watch in production.
Send it on a schedule (same day, same channel) so people know where to look instead of asking in DMs.

API changelog entry

Markdown

Best for: Developer-facing APIs where breaking changes matter most

Date-keyed entries with breaking changes first and a migration path for every one of them. Modeled on the changelogs developers already trust (Stripe-style).

Template

## 2026-07-10

### Breaking changes

- POST /v2/exports now requires an Idempotency-Key header.
  Requests without one will return 400 starting October 1, 2026.
  Migration: generate a UUID per request and reuse it on retries.

### Added

- GET /v2/teams/{id}/invites lists pending invites.
- Optional status filter on GET /v2/webhooks.

### Changed

- Rate limit on POST /v2/webhooks/test raised from 10 to 60
  requests per minute.

### Deprecated

- GET /v1/exports is deprecated and will be removed on
  2027-01-01. Use GET /v2/exports instead.

### Fixed

- Timed-out webhook deliveries are retried with exponential
  backoff instead of being dropped.

How to use it well

Breaking changes always come first, each with a date it takes effect and a concrete migration step.
Deprecations get a removal date the day they are announced, not "in a future release".
Key entries by date rather than version if you ship continuously; API consumers think in "since when", not in your version numbers.

Mobile app store What's new

Plain text

Best for: App Store and Play Store release descriptions

Short, benefit-first lines that survive truncation. The Play Store cuts you off at 500 characters; the App Store shows roughly three lines before "more".

Template

What's new in 4.2

- Invite your whole team at once by uploading a CSV
- Search results now update in seconds
- Fixed a bug where a timed-out sync could drop changes
- Smaller fixes and performance improvements throughout

Something not working? Reach us at [email protected] and a
human will reply.

How to use it well

Put the single best change in the first line; on the App Store that may be all anyone sees without tapping "more".
Stay under 500 characters so the same text works on the Play Store without editing.
Never ship only "bug fixes and improvements". Users read that as "we stopped trying". Name at least one real fix.

Plain-English weekly update

Plain text

Best for: Founders and leads reporting to stakeholders and non-engineers

Three things worth knowing, written as sentences a non-engineer can read. No PR numbers, no jargon, a one-line look ahead.

Template

Subject: What shipped this week (July 6 to 10)

Hi all,

Three things worth knowing from this week:

1. Bulk invites are live. Admins can upload a spreadsheet and
   invite a whole team at once. Support tickets about invites
   should start dropping from Monday.

2. Search got faster. Edits now show up in results within
   seconds. This closes the top complaint from the June
   feedback round.

3. A silent webhook bug is fixed. Deliveries that timed out were
   being dropped without a trace; they now retry automatically.
   If a customer mentioned missing events last month, this was
   why.

Next week: the billing migration lands behind a feature flag,
and the mobile beta opens to the first ten teams.

Questions? Just reply.

How to use it well

Cap it at three items. If everything is worth knowing, nothing is.
Attach each item to a consequence the reader cares about: fewer tickets, a closed complaint, an explained incident.
The "next week" line is what builds trust over time; readers check whether last week's promise shipped.

Feature release notes (problem and solution)

Markdown

Best for: Bigger releases where one feature deserves a real story

A product manager style template: state the problem, what changed, and who it is for. Reads like a small blog post and doubles as launch copy.

Template

# Version 2.4.0 - July 10, 2026

## Bulk invite from CSV

**The problem:** onboarding a 20-person team meant sending 20
invites one at a time. Admins told us it was the most tedious
part of setup.

**What we changed:** upload a CSV with names and emails, review
the list, and send every invite in one click. Duplicates and
existing members are skipped automatically.

**Who it helps:** admins onboarding more than a few people at
once, especially during trials.

## Also in this release

- Search results update within seconds of an edit.
- Timed-out webhook deliveries retry automatically.
- Invoice PDFs load about twice as fast.

How to use it well

Only the headline feature gets the problem-solution treatment; everything else goes in "Also in this release".
Quote the actual user pain in the problem paragraph. Specifics ("20 invites one at a time") beat abstractions ("onboarding friction").
This format recycles well: the same text works for the changelog, the launch email, and a social post.

Hotfix and incident release note

Markdown

Best for: Explaining an urgent fix without a full postmortem

Four questions, answered in order: what happened, who was affected, what was fixed, what the reader should do. Calm and specific beats vague and reassuring.

Template

# Hotfix 2.4.1 - July 12, 2026

**What happened:** between 09:10 and 11:42 UTC on July 12,
webhook deliveries to endpoints that responded slower than 10
seconds were dropped without a retry.

**Who was affected:** teams whose webhook endpoints respond
slowly under load. Roughly 3% of deliveries in that window.

**What we fixed:** deliveries now retry with backoff for up to
24 hours. Events dropped during the incident window have been
replayed.

**What you should do:** nothing, in most cases. If your
integration deduplicates by event ID, replayed events were
ignored automatically. If it does not, check for duplicates
between 12:00 and 13:00 UTC.

How to use it well

Give exact times and honest numbers. "Roughly 3% of deliveries" earns more trust than "a small number of users".
The "what you should do" section is mandatory, even when the answer is "nothing".
Keep it to these four questions. If the incident needs more, write a separate postmortem and link it.

Beta and early access release notes

Markdown

Best for: Keeping beta testers informed and reporting bugs

Sets expectations up front, lists what changed in this build, and is honest about known issues so testers report new bugs instead of known ones.

Template

# Mobile digest beta - build notes, July 10

**Status:** early access. Your data is safe, but the interface
will change between builds.

## New in this build

- First version of the digest view on mobile.
- You can now snooze an alert for one week.

## Known issues

- Snoozed alerts do not yet sync across devices.
- The digest view can take a few seconds to load for teams with
  many repositories.

## Feedback

Post in #beta-feedback or use the in-app "Send feedback" button.
The three most reported issues get priority in the next build.

How to use it well

The known issues list is the whole point: it stops duplicate reports and shows testers you are paying attention.
Say explicitly what is safe (data) and what is not (layouts, flows), so testers know how hard they can push.
Close the loop in the next build's notes: "fixed: snooze now syncs (reported by 6 of you)".

After the template

The template is the easy part. Filling it in is not.

Everyone who searches for a release notes template has lived the same Friday: release day arrives, the changelog is three versions behind, and someone scrolls through git log trying to remember what actually shipped. The template was never the problem. Keeping it filled in, every release, forever, is.

GitLoom removes that chore. It reads your merged pull requests and commits, writes plain-English release notes in the same spirit as the templates above, deduplicated and written to be forwarded without editing, and delivers them to Slack, email, or Telegram. Each report takes custom instructions, so the notes follow your house style. You review, tweak if you want, and share.

releases·GitLoom release notesfridays 16:00

GitLoomApp4:02 PM

Release notes: 3 changes shipped across 2 repos this week.

New: web#512 Bulk invite from CSV (Priya)

Admins can upload a CSV and invite a whole team in one click.

Improved: api#498 Search indexing latency (Jonas)

Edits now show up in search results within seconds instead of minutes.

Fixed: api#505 Webhook retries dropped on timeout (Ale)

Timed-out deliveries now retry with backoff instead of disappearing.

The same notes went out by email. Nothing else shipped, so that is the whole list.

Reply to GitLoom in thread

Drafted from merged PRs. Nobody filled in a template.

Step 01

Install the GitHub App

Grant the repos you want covered. GitLoom detects each repo’s release conventions (version tags, a deploy branch, or continuous to main) automatically.

Step 02