All articles

Updated

Release notes examples and what makes them work

Real release notes from Stripe, Linear, Slack, and GitHub, with what each does well and a sample you can adapt for your first update.

By Colin Armstrong
Faint rows of commit-log lines fade behind one clean release note card, its new, fixed, and breaking sections set beside the headline on Paragraph's near-black ground.

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].

Keep a Changelog warns that commit log diffs make bad changelogs because "they're full of noise" [1]. One noteworthy difference often spans several commits [1], 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]. Its entries state the change, then the action. One entry says it "removes or renames properties on bank account details" [4], and follows with a direct instruction: "Update any code that treats account_number or iban as optional to handle the required status" [4].

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]. 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]. It ends with the exact steps: open a loop's menu and select Save as template [5].

Fixes stay short and specific: "Fixed a startup crash caused by invalid code syntax theme preferences" [5].

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]. A user recognizes that instantly.

Slack also changes tone to match the stakes. Security updates get a flat instruction: "Updating is strongly recommended" [6]. Routine code cleanup gets a joke about a "streak-free shine" [6]. 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]. You can use labels to group pull requests into categories and exclude certain labels or users [7]. GitHub itself advises you to check the generated notes so they include "all (and only)" the information you want [7].

Example

Main reader

What to borrow

Watch out for

Stripe [3][4]

Developers on the API

The change plus the code to update

Too terse for non-technical users

Linear [5]

Product teams

Purpose first, then use cases and steps

Needs real writing time per feature

Slack [6]

Everyday app users

Bugs described as users experienced them

Humor can bury important updates

GitHub generated [7]

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].

A practical checklist:

  • A version number. With Semantic Versioning's MAJOR.MINOR.PATCH format [2], the number itself tells readers how big the change is [2].

  • 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].

  • Security notes. Say plainly whether people should update [6].

Keep an Unreleased section at the top of your log to collect changes as they land [1]. 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]. In practice the two names overlap, and teams use either one for the same kind of page.

Stripe calls its page a changelog [3], and Slack calls its page release notes [6]. 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 reads what merged, leaves out the noise, and writes it for customers rather than for Git [8]. Every entry waits for your approval before it publishes, emails anyone, or posts to a social account [8]. Your first two Changelog campaigns are free [8]. You can read how the Changelog Playbook works, or try it on a public repository without connecting GitHub [10] using this guide.

Sources

  1. Keep a Changelog

  2. Semantic Versioning 2.0.0 | Semantic Versioning

  3. Changelog

  4. Updates the Financial Addresses v2 API shape

  5. Now (Linear changelog)

  6. Slack for Windows - Release Notes | Slack

  7. Automatically generated release notes

  8. Developer changelog, written from your commits | Paragraph

  9. See What's Worth Announcing From Your GitHub Work — Paragraph


More articles

Start with Paragraph today

Paragraph's agent turns your company context into posts, newsletters, and social campaigns, then ships the work you approve.