Engineering

Release Notes Template (and Changelog Template)

Release notes tell users what changed and whether they need to do anything. A changelog records every change, version by version. This template gives you both from the same facts, written once: the changelog as the record, the release note as the version people read.

Updated 2026-10-27

Copy and adapt

The template

Release notes and changelog entryTemplate

[Product] [version]: [what users can do now, in their words]

Version: [x.y.z] Released: {{date}} Availability: [all plans / which plans / rolling out to N percent] Platforms: [web / iOS / Android / API]

[One or two sentences: the most important change, and whether anyone needs to do anything.]

New

[Feature name]. [What it lets you do.] [Link to docs]

Improved

[Existing feature, and what is better, with a number if you have one]

Fixed

[The symptom users saw, now fixed] ([platform or version affected])

Breaking changes and deprecations

[What changes, who is affected, what to do, and by when]

Known issues

[Problem, workaround, expected fix]

Changelog entry

[x.y.z] - YYYY-MM-DD

Added

[New capability]

Changed

[Change to existing behavior]

Deprecated

[Still works, will be removed in version or date]

Removed

[Gone in this version]

Fixed

[Bug fix, with issue number]

Security

[Vulnerability fixed, with advisory link]

5 examples

Examples for different situations

The same structure, filled in for the situations people actually bring to it. Copy the one closest to yours.

1.Major feature release for customers

When it fits: Use this when one feature is the reason for the release, most readers are customers rather than developers, and some of them will need to change a setting.

Major feature release for customersExample 1

Ledgerly 3.0: send recurring invoices automatically

Version: 3.0.0 Released: 2026-11-10 Availability: Business and Enterprise plans Platforms: web, iOS, Android

You can now set an invoice to repeat weekly, monthly or quarterly, and Ledgerly sends it on the date you choose. If you used the old "duplicate invoice" reminder, read the breaking change below.

New

Recurring invoices. Pick a schedule and an end date, and each invoice is created and emailed for you. You can pause or edit future invoices without touching past ones. See "Recurring invoices" in the Help center.
Payment reminders. Send a reminder 3, 7 or 14 days after the due date, per client.

Improved

The invoice list loads in under a second for accounts with 10,000+ invoices (it took 6 seconds).
PDF invoices now include your tax ID on every page, not only the first.

Fixed

Totals were off by one cent when a line used three decimal places (web, since 2.14).

Breaking changes and deprecations

The "duplicate invoice" reminder is replaced by recurring invoices. Existing reminders were converted on 2026-11-10; check Settings > Reminders before 2026-12-01, when unconverted reminders stop.

Known issues

On Android, the schedule picker shows dates in US format regardless of region. Fix in 3.0.1, expected 2026-11-17.

2.Weekly roundup of small updates

When it fits: Use this when you ship continuously, no single change deserves its own announcement, and readers want one short list each week.

Weekly roundup of small updatesExample 2

What changed this week, 2026-11-13

Product: Fieldnote project boards Availability: all plans, web and desktop

Mostly fixes and small improvements this week. Nothing needs action from you.

New

Keyboard shortcut for moving cards. Press M on any card to move it to another column without dragging.
Due date in card previews. Cards now show the due date on the board, in red when it is past.

Improved

Search now matches card comments, not just titles and descriptions.
Board exports to CSV include the assignee's email, as requested in 34 feedback posts.

Fixed

Cards dragged to the last column on a narrow screen sometimes landed in the first column.
The desktop app no longer asks you to sign in again after it updates.
Notification emails showed the board name twice in the subject line.

Next week: the new board permissions are in beta with 20 teams. Reply to this email if you want in.

3.Changelog file for an open-source library

When it fits: Use this when your readers are developers upgrading a dependency, every version needs an entry, and they care more about what breaks than about why you built it.

Changelog file for an open-source libraryExample 3

Changelog

All notable changes to pg-batcher are documented here. The format follows Keep a Changelog, and the project uses Semantic Versioning.

[Unreleased]

Added

Optional jitter on retry backoff (#412)

[2.4.0] - 2026-11-18

Added

batch.flushEvery option to flush on a timer as well as on size (#398)
Type definitions for the onError callback (#405)

Changed

Default batch size raised from 500 to 1,000 rows; set batchSize to keep the old value (#401)

Deprecated

The insertMany alias. Use insert, which accepts arrays. Removal planned for 3.0.0.

Fixed

Connections were not released when a batch failed validation (#396)

Security

Table and column names are now quoted, preventing injection through untrusted identifiers (#409, reported by Kenji Arai)

[2.3.2] - 2026-10-02

Fixed

Crash on Node 22 when the pool was closed during a flush (#388)

4.Internal release notes for support and operations

When it fits: Use this when the audience is your own support, sales and on-call staff, who need to know what will generate questions, what is behind a flag and how to roll back.

Internal release notes for support and operationsExample 4

Internal: web app release 2026.11.24

Deployed: 2026-11-24 14:00 UTC Release owner: Priscila Mendonça Rollback: redeploy 2026.11.17 via the deploy job, about 6 minutes Customer-facing notes: going out 2026-11-25 09:00 UTC

Support should expect questions about the new login screen. Nothing changes for billing.

What customers will notice

New login screen with "Sign in with Microsoft". Old bookmarks to /signin redirect.
CSV import limit raised from 5,000 to 25,000 rows.

Behind a flag (not visible to customers yet)

Team workspaces, enabled for 12 beta accounts listed in the beta tracker. Do not mention to other customers.

Fixed

Ticket 88213 and duplicates: password reset emails delayed up to 20 minutes. Reply macro "Reset delay fixed" is ready.

Known issues

Microsoft sign-in fails for accounts whose email has a plus sign. Workaround: sign in with password. Fix targeted for 2026.12.01 (owner: Gareth Oduya).

Who to ask

5.API deprecation notice

When it fits: Use this when a release removes or changes something developers depend on, and the note has to work as a migration guide with a hard date.

API deprecation noticeExample 5

Webhooks v1 will be retired on 2027-03-31

Version: API 2026-12-01 Announced: 2026-12-01 Affects: integrations receiving v1 webhook payloads Platforms: API

If your integration receives webhooks with "version": 1 in the payload, you need to switch to v2 before 2027-03-31. After that date v1 webhooks stop being sent. We count 214 active integrations still on v1; their owners are getting this note by email as well.

What changes

v2 payloads put the event data under "data" instead of at the top level.
v2 signs every request with a timestamped signature header; v1 had no signature.

What to do

In Settings > Webhooks, add a second endpoint with version 2.
Update your handler to read event fields from "data" and verify the signature.
Confirm v2 events arrive, then delete the v1 endpoint.

Timeline

2027-01-15: dashboard warning on every account still using v1.
2027-03-01: v1 deliveries limited to 1 retry instead of 5.
2027-03-31: v1 deliveries stop.

Known issues

The migration guide's Python sample uses an older SDK. Updated sample by 2026-12-08.

Release notes vs changelog

The two terms get used interchangeably, and most release notes guides treat them as one thing with two names. They are better treated as two documents built from the same facts.

	Changelog	Release notes
Reader	People upgrading: developers, admins	People using the product
Coverage	Every notable change, every version	The changes users will notice
Order	Newest version first, ISO dates	Most important change first
Language	Precise, technical, issue numbers	What you can now do, what is fixed
Lives in	CHANGELOG.md, docs, GitHub releases	In-app panel, email, app stores, blog

A changelog is not a commit log. Commits include merges, refactors and typo fixes that nobody upgrading needs to know about. The changelog is the curated list of notable changes; the release note is the further-curated story of one release.

Where the content comes from

Release notes go wrong when they are written from memory on release day. The reliable path has three steps:

During the cycle, each change that merges adds a line to the Unreleased section of the changelog. The person who made the change writes it, because they know what it does.
On release day, the Unreleased section becomes the new version with today's date.
For users, someone who talks to customers (often product or support) rewrites the items users will notice into release notes, leads with the most important one, and adds the "does this affect me" line.

This keeps the changelog complete and the release notes readable, without anyone reconstructing two weeks of work from pull request titles.

Breaking changes, security fixes and hotfixes

Most guides skip these cases, but they are the ones readers look for.

Breaking changes go at the top of the release note, not in a list at the bottom. Say who is affected, what to do and the deadline. Announce well before removal, with a warning stage in between.
Security fixes go in the changelog's Security group with the advisory link. In public release notes, say what was fixed and whether users need to act (update, rotate a key), without publishing a recipe for the attack before most users have updated.
Hotfixes get a patch version and a one-line entry. Do not fold them silently into the next release; people searching "was this fixed?" need to find the version.

Internal release notes

Support, sales and on-call staff need a different note: what will generate tickets, what is behind a flag and must not be mentioned, how to roll back, and who to ask. Send it before the public notes so nobody hears about a change from a customer first. The internal example above shows the shape.

Common mistakes

"Bug fixes and performance improvements." Says nothing; readers learn to skip your notes.
Ticket numbers instead of symptoms in user-facing notes.
Burying the breaking change under three new features.
Different formats every release. A consistent structure lets readers scan to the section they care about.
No date. Undated notes cannot answer "was this before or after the problem started?"

When to use a different template

Release notes describe what shipped. To plan what ships next, use the product roadmap template. For the bug reports that end up as Fixed lines, the bug report template captures the symptom in a form you can copy straight into the note. And for stakeholders who need progress rather than a feature list, a project status report is the better fit.

Customization tips

Answer "does this affect me?" first
The first sentence should tell a reader whether they can stop reading. Put the action (or "nothing needs action from you") right under the title, before any feature list.
Describe symptoms, not tickets
"Totals were off by one cent when a line used three decimal places" lets users recognize their bug. "Fixed rounding issue (LED-2210)" does not. Keep the ticket number in the changelog, where developers want it.
Keep the changelog in Keep a Changelog format
Newest version first, ISO dates, and the six groups (Added, Changed, Deprecated, Removed, Fixed, Security). An Unreleased section at the top collects changes as they merge, so release day is a rename, not an archaeology project.
Write App Store notes as plain text
App Store and Play Store release notes do not render Markdown. Drop the headings, use short lines with a capitalized lead word (New, Fixed), and keep the first line strong, because the store truncates the rest.
Separate internal notes from public ones
Support and on-call need flags, rollback steps and known issues that customers should not see. Write the internal version first; the public one is a subset of it.
Give deprecations three dates
Announcement, a warning stage, and removal. A single date surprises the people who did not read the first email, and they are always the majority.

In the app

How to do this in Scribelet

Open Desk Settings, then Templates, tap Add Template, paste the template above, choose the General category and set #release as a default tag. {{date}} fills in the release date when you create the note.
Keep one running note called [[Changelog]] with an Unreleased section at the top. Add a line when each change merges; on release day, copy the section into a new release note from the template and link it back.
If your team uses an AI coding agent, connect it to Scribelet's MCP server. Claude Code or Cursor can then read and update your changelog note, for example adding a line under Unreleased when it opens a pull request.
With the GitHub connector, opt the release note in from its Settings. Background verification (Pro) checks claims such as "default batch size is 1,000" against the repository and proposes a correction before the note goes out.
Ask the AI chat "when did we change the default batch size, and why?" and it answers from your release notes and changelog with citations to the specific version.

Templates, template variables and AI generation are documented in Note templates.

Frequently asked questions

What is the difference between release notes and a changelog?

A changelog is the complete, chronological record of changes, version by version, written for people who upgrade: usually developers. Release notes are a curated summary of one release, written for the people who use the product, and they explain what changed in terms of what users can now do. Many teams keep a changelog as the source of truth and write release notes from it.

What should release notes include?

The version and date, who it is available to, a first sentence that says whether the reader needs to act, then what is new, improved and fixed. Add breaking changes with a deadline and known issues with a workaround whenever they exist; those are the sections readers look for first.

How do you write good release notes?

Write from the user's side: name the thing they can now do, or the symptom that is now fixed. Lead with the change that matters most, keep each item to one or two sentences, and link to documentation for detail. The examples above show the same structure written for customers, developers and internal staff.

How long should release notes be?

As short as the release allows. A weekly roundup is five to ten bullets. A major release can run a page, but the first two sentences should still stand alone, because many readers stop there.

Can I generate release notes from commit messages?

You can generate a draft changelog from commits or merged pull request titles, but raw commit logs are noisy and written for the team, not for users. Curate the list into the changelog groups, then rewrite the items users will notice into release notes.

Where should release notes be published?

Wherever readers already look: an in-app "What's new" panel or a changelog page for customers, the CHANGELOG.md file and GitHub releases for libraries, the app stores for mobile, and email for anything that requires action. Internal notes go to the support and operations channels before the public notes go out.

Release notes written from what actually shipped

Keep a running changelog in Scribelet, draft each release from this template, and let your notes answer "when did that change?" with a citation. Connect your repository and verification flags claims the code does not back up. Encrypted, free to start.

Start your changelog

or get the app

Download on theApp Store

Free plan, no credit card. See pricing

Product

Bug Report Template

A good bug report lets someone who has never seen the problem make it happen on their own machine. This template covers the fields every bug report template has (steps, expected, actual, environment, severity) and adds the ones most leave out: how often it reproduces, whether it is a regression, and the workaround.

Product

Product Roadmap Template

A roadmap is a promise about priorities, not a schedule. This template ties every initiative to a goal, says how confident you are in each date, keeps a visible list of what you are not doing, and logs every change with its reason. Copy it as-is, or start from the roadmap example closest to your audience.

Product

PRD Template (Product Requirements Document)

A PRD (product requirements document) says what problem a release solves, for whom, how you will know it worked, and what it deliberately will not do. This template keeps it short enough to be read, and adds what most PRD templates leave out: a status, a decision log, and open questions with owners and dates.

Projects

Project Status Report Template

A status report tells readers in thirty seconds whether the project is on track, what changed since last time, and what you need from them. This template defines green, amber and red up front, so the color means the same thing every week.

Article

Pull request template

From the Scribelet blog

Article

Docs as code

From the Scribelet blog