A release note tells a reader what changed and what, if anything, they need to do. A changelog keeps notable changes grouped by version. You can use the same source notes for both, but the changelog is the record and each release note is the explanation.

What release notes template can I copy?

Start with this Markdown template. Delete a section when there is nothing useful to say; keep the affected audience and required action visible.

md
## [Product] [version] — [YYYY-MM-DD]

[One sentence: what this release changes and who should care.]

### Breaking changes
- [What stops working, who is affected, the replacement, and deadline.]

### Added
- [What the reader can do now] — [where to find it or a docs link].

### Changed
- [What works differently, who is affected, and what to do.]

### Fixed
- [What the reader saw] — [what works now and who was affected].

### Security
- [Affected versions, impact, fixed version, and advisory or CVE link if public.]

### Deprecated
- [What is being phased out, the replacement, and removal date.]

### Removed
- [What is no longer available and what replaces it, if anything.]

### What you need to do
- [Action and deadline, or “Nothing; this change is automatic.”]

For a release with one small fix, keep the version line and one Fixed bullet; omit the rest.

What release notes format fits this change?

Choose the length by the reader’s decision. The labels come from Keep a Changelog, plus a separate breaking-change heading, which that convention asks you to call out but does not name as a category. The reader column builds on GitHub’s release-note guidance, which asks whether a change applies to the reader, what it is, and where to read more. The examples below are illustrative templates, not claims about a real product.

ChangeWhat the reader needsLengthExample line
FixRecognize the old symptom and know whether it affected themOne sentenceFixed: Exported CSV files no longer drop rows when a filter is active.
Small improvementNotice the changed behavior or benefitOne sentenceChanged: Search keeps your selected date range when you open a result.
New featureUnderstand what they can do and where to startOne to three sentences; add a link or steps if neededAdded: Pin a saved filter in Logs to reuse it or share its URL with a teammate.
Breaking changeIdentify impact, replacement, migration step, and deadlineSeparate heading plus stepsBreaking: Replace `apiKey` with `token` before upgrading to v3.0 on December 1.
Security fixUnderstand affected versions, impact, fixed version, and advisorySeparate, precise entry; include severity or CVE when availableSecurity: Versions 2.1–2.3 are affected by [impact]. Upgrade to 2.3.1; see [advisory].
DeprecationKnow what will disappear, when, and what replaces itOne sentence for a distant removal; steps and dates as removal nearsDeprecated: `apiKey` warns in 2.9 and is removed in 3.0; switch to `token`.

Use a Removed entry when the removal ships. Keep a deprecation visible before that point so readers have time to move. The Keep a Changelog categories are Added, Changed, Deprecated, Removed, Fixed, and Security; use the exact labels when you adopt that convention.

SemVer assigns MAJOR for incompatible API changes, MINOR for adding backward-compatible API functionality, and PATCH for backward-compatible bug fixes. That is a rule for versioned public APIs, not a measure of how many paragraphs to write. Semantic Versioning gives the definitions; pair the version with a note that explains the reader impact.

How do I write release notes without a full paragraph?

Use one sentence when it contains the change and the reader’s next step. A bullet is enough for a small improvement or fix; add a heading, example, or migration steps when the reader needs to make a decision.

  1. What changed? Name the behavior, not the ticket or implementation.
  2. Who is affected? State the role, plan, version, or say that everyone is.
  3. What should they do? Give the setting, replacement, deadline, or say no action is needed.
  4. Where can they learn more? Link to instructions or a security advisory when one is public.

For example, “Bug fixes and improvements” answers none of these. “The billing export now includes rows matching a saved filter; no action is needed” names the behavior and next step. Avoid commit lists: Keep a Changelog describes a changelog as a curated list of notable changes, not a raw history of code changes.

What do release notes examples look like for the same change?

One showcase input, written three ways: a plain prompt output and two outputs with different approaches and forms. The example input describes saved filters in a fictional product, Tidepool; it is showcase data, not a customer story.

The plain arm uses the same task, input, facts, and voice rules as the protocol arm, with no protocol. The showcase uses three plain runs per model. These are individual examples from a small sample, not a general result.

Plain Claude output (one of three plain runs; showcase example):

Saved filters in the logs view

You can now save a query in the Tidepool logs view, such as status:500 team:billing, pin it for quick access, and share it with teammates as a link.

Saved filters are behind a feature flag until Thursday, November 12. If you use the logs view, you don't need to do anything. The feature turns on for everyone that day. To try it earlier, ask your workspace admin to enable the flag.

Claude with protocol draw why_we_changed (medium entry, code snippet, problem-first opener):

Saved filters in the logs view

Retyping the same query every time you open the logs view gets old fast, and pasting a long filter string into chat so a teammate can see what you see is easy to get wrong. Tidepool now lets you save a filter and share it as a link.

Type a query, pin it, and it stays in your saved filters for next time:

text
status:500 team:billing

Copy the link from a pinned filter and anyone who opens it lands in the logs view with that exact query already applied. No more "which filters did you use?" back and forth during an incident.

A shared link carries the query, not a snapshot of the results. When someone opens it, they see the logs that match right now, so what they see can differ from what you saw when you sent it. We chose this because a filter you can reuse every day is more useful than a frozen view that goes stale. If you need to point at a specific moment, include a time range in the query.

Who this affects: anyone who uses the logs view. Saved filters sit behind a feature flag until Thursday, so you may not see them yet. On Thursday they turn on for everyone, and you don't need to do anything. Your existing queries and workflows keep working exactly as before.

Claude with protocol draw outcome_first (short paragraph, bullets, user-benefit opener):

You can now save a logs query and hand it to someone as a link, so you stop retyping the same filter every morning.

  • Pin any query in the Tidepool logs view, such as status:500 team:billing, and it stays in your saved filters.
  • Share a pinned filter by copying its link. Whoever opens it lands on the same filtered view.
  • This affects anyone who uses the logs view. Until Thursday, November 12, it is behind a feature flag, so enable the flag if you want it early. After that it is on for everyone, and you need to do nothing.

The plain sample leads with nearly the same headline and feature description across its three Claude runs. In this case, plain Claude outputs run 77 to 126 words; the three protocol outputs run 103 to 234 words (counted as whitespace-separated words, Markdown included). This small sample shows variation in structure and length, not a general rate or evidence that a particular wording works better with readers. The live examples show other showcase cases.

What is the difference between a release notes format and a changelog format?

Release notes explain what a release means to a reader; a changelog records notable changes in version order. For a repository CHANGELOG.md, keep an Unreleased section and move its entries under a dated version when you release. For a product update, keep the same facts but lead with the user action or benefit.

md
# Changelog

## [Unreleased]
### Added
- [New capability and who can use it]

### Changed
- [Changed behavior and any required action]

### Deprecated
- [Feature, replacement, and planned removal]

### Removed
- [Feature removed in this version]

### Fixed
- [Visible problem that is fixed]

### Security
- [Public security fix or advisory]

## [1.4.2] - 2026-11-12
### Fixed
- [Notable fix, described for users]

Keep the section names and ordering consistent with your project’s chosen convention. For changelog examples from real products, Stripe’s API changelog labels each entry with the products it affects and groups breaking changes under their own heading per version. GitHub’s changelog groups posts as New Releases, Improvements, and Retired. Choose the one that helps your readers scan the changes they need.

If you generate notes from CI, keep the source facts in your release workflow and send them through the HTTP API. We make Unsame; its release-notes playbook draws a different approach and form for a repeated writing task, while your own model writes the text. See Unsame and MCP vs API for the integration choices.

When should a release note be just one line?

Use one line when the change is narrow, low-risk, and needs no setup or decision. Expand it when a reader must upgrade, migrate, change a setting, identify an affected version, or assess a security issue. A simple test: if a reader could reasonably ask “does this affect me?” or “what do I do now?”, include that answer.

Skip “bug fixes and improvements” when you can name even one visible behavior. If there is no user-visible change, no action, and no reason the reader needs to know, it can stay in the engineering history instead of the public notes.

Try it

Start with a free Unsame account if you want a playbook to vary release-note approaches across repeated updates. Keep the facts, version, and impact accurate in every draft, then review the note before publishing.

— Don