---
title: "Release notes examples and what makes them work"
description: "Real release notes from Stripe, Linear, Slack, and GitHub, with what each does well and a sample you can adapt for your first update."
canonical_url: "https://paragraph.com/articles/release-notes-examples-and-what-makes-them-work"
author: "Colin Armstrong"
published: "2026-11-12T16:00:03.092Z"
updated: "2026-11-16T22:16:19.625Z"
---

# Release notes examples and what makes them work

*   [What makes a good release note?](#what-makes-a-good-release-note)
    
*   [Release notes examples worth learning from](#release-notes-examples-worth-learning-from)
    
*   [What should be included in release notes?](#what-should-be-included-in-release-notes)
    
*   [What's the difference between a changelog and release notes?](#whats-the-difference-between-a-changelog-and-release-notes)
    
*   [A release note sample you can adapt](#a-release-note-sample-you-can-adapt)
    
*   [Start with your next release](#start-with-your-next-release)
    

You shipped the update. Now you have to explain it to people who never saw the pull requests. Most first release notes fail in one of two ways: they read like a commit log, or they say so little that nobody knows what changed.

What makes a good release note?
-------------------------------

A good release note tells a specific reader what changed and what it means for them. It's written for people, and it groups many commits into one clear change \[[1](https://keepachangelog.com/en/1.1.0/)\].

Keep a Changelog warns that commit log diffs make bad changelogs because "they're full of noise" \[[1](https://keepachangelog.com/en/1.1.0/)\]. One noteworthy difference often spans several commits \[[1](https://keepachangelog.com/en/1.1.0/)\], so describe the outcome once. Your reader cares about the result, and the steps behind it rarely matter to them.

Release notes examples worth learning from
------------------------------------------

Each of these teams writes for a different reader, and it shows in how they phrase changes.

### Stripe: tell developers exactly what to do

Stripe's changelog exists to help readers "keep track of changes and upgrades to the Stripe API" \[[3](https://docs.stripe.com/changelog)\]. Its entries state the change, then the action. One entry says it "removes or renames properties on bank account details" \[[4](https://docs.stripe.com/changelog/endive/2026-10-28/financial-addresses-v2-api-shape-updates)\], and follows with a direct instruction: "Update any code that treats `account_number` or `iban` as optional to handle the required status" \[[4](https://docs.stripe.com/changelog/endive/2026-10-28/financial-addresses-v2-api-shape-updates)\].

That second sentence is the part worth copying. If a change can break someone's work, say what they need to edit.

### Linear: lead with what the feature does for you

Linear opens a feature by stating its purpose: "Loops automate product work by responding to changes in Linear and connected tools" \[[5](https://linear.app/changelog)\]. Then it gives concrete uses, like answering product questions in a Slack channel or drafting a QA plan when a pull request gets a "ready for testing" label \[[5](https://linear.app/changelog)\]. It ends with the exact steps: open a loop's menu and select Save as template \[[5](https://linear.app/changelog)\].

Fixes stay short and specific: "Fixed a startup crash caused by invalid code syntax theme preferences" \[[5](https://linear.app/changelog)\].

### Slack: describe bugs the way users felt them

Slack writes fixes from the user's side. "Sharing your screen during a huddle would sometimes cause Slack to crash without warning" \[[6](https://slack.com/release-notes/windows)\]. A user recognizes that instantly.

Slack also changes tone to match the stakes. Security updates get a flat instruction: "Updating is strongly recommended" \[[6](https://slack.com/release-notes/windows)\]. Routine code cleanup gets a joke about a "streak-free shine" \[[6](https://slack.com/release-notes/windows)\]. Humor works for low-stakes notes. It doesn't belong next to anything urgent.

### GitHub: a generated starting point

GitHub can generate release notes that list merged pull requests, contributors, and a link to the full changelog \[[7](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes)\]. You can use labels to group pull requests into categories and exclude certain labels or users \[[7](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes)\]. GitHub itself advises you to check the generated notes so they include "all (and only)" the information you want \[[7](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes)\].

| Example | Main reader | What to borrow | Watch out for |
| --- | --- | --- | --- |
| Stripe \[[3](https://docs.stripe.com/changelog)\]\[[4](https://docs.stripe.com/changelog/endive/2026-10-28/financial-addresses-v2-api-shape-updates)\] | Developers on the API | The change plus the code to update | Too terse for non-technical users |
| Linear \[[5](https://linear.app/changelog)\] | Product teams | Purpose first, then use cases and steps | Needs real writing time per feature |
| Slack \[[6](https://slack.com/release-notes/windows)\] | Everyday app users | Bugs described as users experienced them | Humor can bury important updates |
| GitHub generated \[[7](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes)\] | Teams releasing on GitHub | Fast, structured list from merged PRs | Needs a review before you publish |

What should be included in release notes?
-----------------------------------------

Include the version, what's new, what's fixed, and anything that could break. If you only cover one thing, Keep a Changelog says to list "deprecations, removals, and any breaking changes" \[[1](https://keepachangelog.com/en/1.1.0/)\].

A practical checklist:

*   **A version number.** With Semantic Versioning's MAJOR.MINOR.PATCH format \[[2](https://semver.org/)\], the number itself tells readers how big the change is \[[2](https://semver.org/)\].
    
*   **New features.** What it does, one example use, and how to find it.
    
*   **Fixes.** Written as the symptom the user saw.
    
*   **Breaking changes.** What changed and what the reader must update, like Stripe's entries \[[4](https://docs.stripe.com/changelog/endive/2026-10-28/financial-addresses-v2-api-shape-updates)\].
    
*   **Security notes.** Say plainly whether people should update \[[6](https://slack.com/release-notes/windows)\].
    

Keep an `Unreleased` section at the top of your log to collect changes as they land \[[1](https://keepachangelog.com/en/1.1.0/)\]. It saves you from rebuilding the list from memory on release day.

What's the difference between a changelog and release notes?
------------------------------------------------------------

A changelog is a running, chronological list of notable changes for every version of a project \[[1](https://keepachangelog.com/en/1.1.0/)\]. In practice the two names overlap, and teams use either one for the same kind of page.

Stripe calls its page a changelog \[[3](https://docs.stripe.com/changelog)\], and Slack calls its page release notes \[[6](https://slack.com/release-notes/windows)\]. Pick the term your readers expect and keep the principles the same.

A release note sample you can adapt
-----------------------------------

Here's a simple template built from the patterns above:

    Version 2.4.0
    
    New
    - Saved filters: Save any search as a filter and reopen it from the sidebar.
      Open a search, click Save, and name it.
    
    Fixed
    - Exports would sometimes stop at 1,000 rows. Large exports now finish.
    
    Breaking
    - The `status` field is now required. Update any code that sends it as optional.
    

Swap in your own changes. Keep each line about the reader and what they'll notice.

Start with your next release
----------------------------

If turning merged work into readable notes is the tedious part, Paragraph's [Changelog Playbook](https://paragraph.com/agents/changelog) reads what merged, leaves out the noise, and writes it for customers rather than for Git \[[8](https://paragraph.com/agents/changelog)\]. Every entry waits for your approval before it publishes, emails anyone, or posts to a social account \[[8](https://paragraph.com/agents/changelog)\]. Your first two Changelog campaigns are free \[[8](https://paragraph.com/agents/changelog)\]. You can read [how the Changelog Playbook works](https://paragraph.com/articles/introducing-the-changelog-playbook), or try it on a public repository without connecting GitHub \[[10](https://paragraph.com/articles/see-whats-worth-announcing-from-your-github-work)\] using [this guide](https://paragraph.com/articles/see-whats-worth-announcing-from-your-github-work).

Sources
-------

1.  [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
    
2.  [Semantic Versioning 2.0.0 | Semantic Versioning](https://semver.org/)
    
3.  [Changelog](https://docs.stripe.com/changelog)
    
4.  [Updates the Financial Addresses v2 API shape](https://docs.stripe.com/changelog/endive/2026-10-28/financial-addresses-v2-api-shape-updates)
    
5.  [Now (Linear changelog)](https://linear.app/changelog)
    
6.  [Slack for Windows - Release Notes | Slack](https://slack.com/release-notes/windows)
    
7.  [Automatically generated release notes](https://docs.github.com/en/repositories/releasing-projects-on-github/automatically-generated-release-notes)
    
8.  [Developer changelog, written from your commits | Paragraph](https://paragraph.com/agents/changelog)
    
9.  [See What's Worth Announcing From Your GitHub Work — Paragraph](https://paragraph.com/articles/see-whats-worth-announcing-from-your-github-work)
