SaaS Release Notes Template (with examples and AI-from-GitHub workflow)

The template (copy and paste)

Drop this into your changelog tool, your team's release-prep doc, or your CHANGELOG.md and fill in the brackets. Each section is optional except the title and items.

# [Release Title]

**Version:** [vX.Y.Z]
**Released:** [YYYY-MM-DD]

[1-2 sentence summary of what this release is about. What changed for your users? Why does it matter?]

## ✨ New features

- **[Feature name]** — [One-sentence description of what users can now do, written from their point of view, not yours. Link to docs if helpful.]
- **[Feature name]** — [Description.]

## 🔧 Improvements

- [Improvement, phrased as a user-visible benefit. Avoid implementation details.]
- [Improvement.]

## 🐛 Fixes

- [Bug, described as the problem that's now resolved. Not the commit message.]
- [Bug.]

## 🔒 Security

- [Security update, with appropriate vagueness — enough to inform, not enough to enable.]

## 📦 Migration notes (optional)

[Only include if breaking changes or required actions. Otherwise omit this section entirely.]

---

[Optional closing line — what to look forward to next, link to feedback, etc.]

A filled example

This is what a release entry looks like with real content. Compare to the template above.

# Audience segmentation, custom domains, and 12 fixes

**Version:** v2.3.0
**Released:** 2026-05-15

This release adds two features Team subscribers have been asking for since beta — release segmentation by user group, and custom-domain support for hosted changelogs — plus a batch of widget reliability fixes from the last sprint.

## ✨ New features

- **Audience segmentation** — Target individual release items at user groups you define (beta users, enterprise tier, internal team). Items you don't restrict stay visible to everyone. [Docs →]
- **Custom domain** — Serve your hosted changelog from `changelog.yourapp.com` with full HTTPS. SSL is automatic. [Docs →]

## 🔧 Improvements

- The widget unread badge now updates within 200ms instead of on next page load
- Subscriber import accepts CSV files up to 50,000 rows (was 5,000)
- Magic-link expiry extended from 15 to 60 minutes based on subscriber feedback

## 🐛 Fixes

- Widget no longer reopens on its own after a user closes it inside an iframe
- Email notifications now correctly use the project's custom sender domain (was falling back to default on first send)
- Subscriber export now includes the unsubscribe reason when one was provided

## 🔒 Security

- Patched a session-handling edge case affecting accounts with more than 100 team seats. No customer data was exposed; details available on request.

---

Coming next: webhook events for individual item publishes (currently fires only on release publish), and richer analytics breakdowns by user group.

When to use this template

This template is built for the standard SaaS release cadence — weekly to monthly releases that mix new features, improvements, and fixes. It works for:

• Web SaaS apps shipping from a single product team
• Developer-tool companies whose users care about details (the audience expects categorization)
• Indie founders who want a consistent format from release one

It's less appropriate for:

• API-only releases or breaking-change-heavy changelogs — use an API release notes template instead
• Pure bug-fix patches — use a bug fix release notes template for less ceremony
• Internal-only release logs — use an internal release notes template

Why this structure works

Three principles drive the template:

1. Lead with summary, not detail. Most readers skim. The 1-2 sentence summary tells them whether to read further. The categorized items reward those who do.
2. Group by reader-facing category, not by code change type. "Features / Improvements / Fixes / Security" maps to what users care about — not "front-end / back-end / infra / chore" which is engineering's mental model.
3. Write items from the user's point of view. "Widget no longer reopens after close" is what a user experienced. "Fixed iframe state-leak in onClose handler" is what your engineer wrote in their commit. The release notes need the first form.

Mistakes to avoid

• ❌ Pasting raw commit messages or PR titles. They're written for other engineers, not your users.
• ❌ Burying breaking changes inside the Improvements section. Use a dedicated Migration notes block.
• ❌ Listing every change you shipped. If a user can't perceive it (CI tweaks, refactors, dependency bumps), it doesn't belong here.
• ❌ Skipping releases that are "just fixes." Consistent cadence builds trust; a 3-month gap doesn't.
• ❌ Vague language. "Various improvements to performance" is filler. "Page load dropped from 800ms to 200ms" is content.

How to generate this from your GitHub PRs (the 30-second version)

If you're already merging PRs with reasonable titles and descriptions, you don't need to write this template by hand for every release. Herald reads your merged PRs and drafts a release in exactly this structure — automatically.

1. Connect your GitHub repo in Settings → Integrations → GitHub (public or private with the Herald GitHub App).
2. Open a new release and pick YOLO mode. Choose your source: last 30 days of merged PRs, branch-to-branch diff, or release-to-release diff.
3. Herald drafts the release in this format, categorizes each item, and leaves everything editable.
4. Review, edit, publish. Herald also publishes back to GitHub Releases (Team+) so your engineering audience gets it too.

The PR-to-template pipeline is the wedge Herald is built around — see the Aggregating multi-repo changelogs guide if you ship from more than one repo, or the Herald and GitHub Releases guide for the full bidirectional flow.

---

Start a 14-day Herald trial and have a populated changelog in your customers' inbox by lunch — no credit card, full Team features.