How to Write Release Notes: Template and Example

Release notes are short documents, written for the people who use a product, that describe what changed in one software release, who the change affects, and what those users need to do. A release note usually has a header with the product name and the version or date, a one-line summary, and grouped entries for new features, improvements, bug fixes, and known issues. Release notes differ from a changelog: a changelog is the complete, technical, chronological record of every change, and release notes are the curated, plain-language version of one release.

To write release notes, collect the changes in the release, keep only the ones a user notices, group them by type, describe each one by what the user can now do, and say which users or plans get it. That last part is harder when a release ships behind feature flags, because the deploy and the change a customer sees happen at different times. This guide is for product managers, writers, and engineers who publish release notes. It covers what to include, a template and an example, the writing steps, and how to list changes shipped behind flags, with output recorded in Loglune on October 6, 2026. It does not cover release notes for a specific vendor’s product, such as Salesforce or iOS.

What are release notes?

Release notes are the announcement that goes with a software release. They are documents that describe important information about a distribution of a hardware or software product, typically shared with end users, customers, and clients. They accompany an update to a product already in use, and they can also accompany a beta release.

A release note answers 3 questions for the reader: what changed, why it matters to me, and whether I have to do anything. A release note is a brief, user-facing report that explains what changed, why it matters, and who it affects.

Release notes are not a user guide and not a legal document. With no standard, format and content vary, and release notes are generally a terse summary of recent changes written in the present tense.

Release notes vs changelogs

Release notes and changelogs both record changes, and they differ in audience, scope, and wording.

	Release notes	Changelog
Reader	Users, customers, support, sales	Developers and technical users
Scope	One release, curated	Every notable change, cumulative
Wording	Plain language, framed by user impact	Technical: features, fixes, refactors, API changes
Typical source	Product manager or writer, from engineering input	Commits, pull requests, version control logs
Order	Newest release first, grouped by type	Reverse chronological, entry by entry

A changelog is a file, article, or webpage listing all notable changes, often with references to specific commits. Release notes are the plain-language announcement whose main purpose is to explain the effect on the user. Some teams use the two terms interchangeably.

In practice, many products publish release notes on a page called a changelog. The distinction still matters when you write: a changelog entry can say “Refactored the invoice exporter,” while a release note has to say “You can now export invoices as CSV from the Billing page.”

A third record sits below both. Version control system logs, such as git log, hold the commit ID, author, date, message, and file changes for every commit. Use them as a source for generating release notes, not as something to publish to users.

What to include in release notes

A release note covers the following elements. Short releases can drop the ones that are empty.

1. Header: Product name, version number or release date, and the platform or environment if it matters (web, iOS, API).
2. Summary: One or two sentences on what the release does and who it affects. Readers who scan read this line and stop.
3. New features: Name each feature and say what the user can now do, not how it was built.
4. Improvements: What works differently from the user’s side, with a number when you have one.
5. Bug fixes: What the user saw before and what happens now.
6. Availability: Which plans, regions, or user groups get each change, and when. This line is required whenever a change is rolled out gradually or limited to some customers.
7. Action required: Deprecations, breaking API changes, settings to update, and deadlines.
8. Known issues: What is not fixed yet, with a workaround if there is one.
9. Where to get help: A link to the docs, the support contact, or the feedback post the change answers.

The longer list for formal release notes adds the issue summary, steps to reproduce, resolution, end-user impact, and support impact for each fixed bug. Use that longer form for enterprise or regulated software, where support teams and administrators read the notes before upgrading.

Types of release notes

The depth of a release note follows the size of the change.

Type	What it covers	Length
Major release	New features, large UI changes, new capabilities	A short paragraph per feature, with a screenshot or GIF and a link to docs
Minor update	Small improvements and UX changes	One to three lines per item
Bug fix release	Resolved issues	A list: what the user saw, what happens now
Security update	Fixed vulnerabilities	Brief and factual, without exploit details

Release notes template

Copy this template and delete the sections that are empty for the release.

# [Product] [version] release notes ([Month Day, Year])

[One sentence: what this release does and who it affects.]

## New
- **[What the user can now do]**: [1 to 2 sentences on the problem it solves].
  Available to: [plans, platforms, or "all customers"]. [Link to docs]

## Improved
- [What works differently, from the user's side, with a number if you have one]

## Fixed
- [What the user saw before] is fixed. [What happens now].

## Action required
- [Deprecation, breaking change, or setting to update, with the deadline]

## Known issues
- [Issue] [Workaround or expected fix date]

Questions? [Link to help center or support contact]

Release notes example

The example below fills in the template for a fictional billing product. The availability line says which customers get each change, because the two changes ship to different groups.

# Acme Billing 2026.10 release notes (October 6, 2026)

This release adds a new checkout for Enterprise customers and invoice export for everyone.

## New
- **Export invoices as CSV**: download any invoice from Billing > Invoices
  to import it into your accounting tool. Available to: all customers.
- **New checkout**: a one-page checkout with saved payment methods.
  Available to: Enterprise plan. Other plans keep the current checkout.

## Known issues
- The new checkout does not support purchase order numbers yet.
  Use the current checkout for orders that need one.

Questions? Contact support@acme.example.

How to write release notes in 6 steps

1. Collect the changes: Pull the merged pull requests, the closed issues, and the feature flag changes that shipped since the last release. GitHub’s automatically generated release notes produce a list of merged pull requests, a list of contributors, and a link to a full changelog for a Git tag, which is a useful starting list.
2. Keep only what a user notices: Drop refactors, dependency bumps, and internal tooling unless they change behavior, speed, or security.
3. Group by type: Put entries under New, Improved, Fixed, Action required, and Known issues. GitHub can do part of this with pull request labels in a .github/release.yml file.
4. Rewrite each entry around the user: Start with what the user can now do or what no longer goes wrong. ProductPlan lists technical language, vague entries, and length as the 3 reasons few people read release notes, and recommends plain language, short notes, logical grouping, relevant links, and the company’s own voice.
5. State availability: For every entry, write who gets it: all customers, one plan, one platform, or a percentage during a staged rollout. Check this against what actually shipped, not against the plan from the sprint start.
6. Review and publish: Have support and the engineer who built each change read the draft, then publish it where users look: the changelog page, an in-app message for changes users will meet in their next session, and email for large changes.

Automate the list of changes and edit the wording by hand. Steps 1 and 3 can come from pull requests, issue trackers, or flag versions, but generated lists describe code changes, and users need to know the effect and who gets it, which is the work of steps 4 and 5.

Who writes release notes, and who reads them?

Release notes are usually written by a product manager, a product marketing manager, or a technical writer, with engineering supplying the raw material. The common split is engineering providing ship logs, commit messages, and specs, while a PM or product marketer turns them into customer-facing language, with one named owner so the notes actually get published.

The readers are wider than the users who asked for a feature. They include power users and technical users, prospects checking whether a product is actively maintained, support and sales teams who need to answer customers, and the people whose feature requests a release closes. Each group reads the notes for a different reason, which is why the summary line and the availability line carry the most weight.

Release notes for changes shipped behind feature flags

When a team ships behind feature flags, the deploy is not the release. The code for a new checkout can be in production for weeks while a flag keeps it off, and the customer-visible change happens when someone edits the flag. Commit history and generated pull request lists then describe what was deployed, not what customers got. Release notes, changelogs, and version control system logs are records of code changes; none of them records which customers a flag change reached and when.

The availability line of a release note needs the flag record instead: which flags changed between the last release and this one, the targeting before and after, and the time each change went live.

Loglune keeps that record. Each flag edit is appended as a change event, and a publish turns the draft into an immutable version with a number that only increases, with an optional note of up to 200 characters and a report ID. Two read operations then give the release note writer what they need:

• The diff between two published versions returns every changed flag with its full definition before and after, plus the publish watch findings for the same pair.
• The audit lists change events with the actor, the time, the state before and after, and the version each event first shipped in. An event still in the draft shows null, so an unpublished change does not end up in the notes.

What the output looks like

We ran the shipped control route on a local test database on October 6, 2026, with editorial example flags. The run created checkout-v2 and invoice-export, both off by default, and published version 1. It then added a rule to checkout-v2 that serves on to contexts whose plan is enterprise, switched the default of invoice-export to on, and published version 2 with the note "Release 2026.10: new checkout for enterprise plan, invoice export for all" and the report ID "REL-2026-10". Finally, it switched the default of checkout-v2 to on without publishing.

The diff between version 1 and version 2 returned "change": "changed" for both flags. For checkout-v2, "rules": [] before and, after, a rule with "id": "enterprise", the clause "attribute": "plan", "op": "in", "values": ["enterprise"], and "variationId": "on". For invoice-export, "defaultVariationId": "off" before and "defaultVariationId": "on" after. The diff also returned the publish watch finding for the default change:

"findings": [
  {
    "kind": "defaultFlip",
    "flagKey": "invoice-export",
    "before": "off",
    "after": "on",
    "severity": "high"
  }
]

The audit listed 5 events, each with the version that first shipped it.

seq	at	targetKey	change	publishedIn
1	2026-10-06T09:00:01.000Z	checkout-v2	create, default off	1
2	2026-10-06T09:00:02.000Z	invoice-export	create, default off	1
3	2026-10-06T09:00:04.000Z	checkout-v2	add rule: plan in enterprise gets on	2
4	2026-10-06T09:00:05.000Z	invoice-export	default off to on	2
5	2026-10-06T09:00:07.000Z	checkout-v2	default off to on, rules removed	null

Version 2 itself was published at "2026-10-06T09:00:06.000Z", and reading version 2 returned the note and report ID stored with it.

Those 2 responses map directly to the release note example above. Events 3 and 4 shipped in version 2, so they are the entries for this release: the new checkout for the Enterprise plan and invoice export for all customers. Event 5 shows null, so the change that would turn the new checkout on for everyone stays out of the notes until a later version ships it.

When a release causes a problem after it ships, Loglune can add a note to the published version later without changing the version or its original note, which gives the Known issues line a dated record. A rollback publishes a new version with the same contents as an earlier one, so the next release note can say exactly which version customers are back on. To check what one customer saw in a given version, the SDK can evaluate that version for a test context with the X-Loglune-Version header, on every plan.

FAQ

Is it release note or release notes?

Both forms are used. “Release notes” is the common name for the document that covers one release, and “a release note” usually means a single entry or a short note for a small update.

What are new release notes?

New release notes are the notes for the latest version of a product. Vendors usually publish them on a release notes or changelog page, newest first, so users can see what changed since the version they last used.

Writing release notes that match what shipped

Release notes work when each entry says what the user can now do and who gets it. Start from the changes in the release, keep what users notice, group them, write them in plain language, and check the availability of each change against what actually shipped. For changes behind feature flags, take that availability from the published flag versions: the diff between the last release’s version and the new one, and the audit’s first-shipped version for each change.