What should release notes include?

Release notes should identify the product version and date, summarize the customer-visible value, list relevant additions, changes, and fixes, and state any deprecations, removals, security updates, known issues, breaking changes, or migration steps. End with links to documentation and support.

How long should release notes be?

Use the shortest version that lets the affected reader understand what changed and what to do next. A patch may need a summary and one fix. A major release may need several categorized changes, screenshots, known issues, migration steps, and links to deeper documentation.

What is the difference between release notes and a changelog?

A changelog is the maintained chronological record of product changes. Release notes explain one release to its audience and may include more context, examples, migration help, and announcement copy. One changelog entry can link to a longer set of release notes.

Should release notes list every technical change?

No. User-facing notes should focus on changes a customer can notice, use, or must respond to. Put internal refactors, routine dependency updates, and implementation detail in engineering records unless they affect behavior, compatibility, security, performance, or required migration.

How often should release notes be published?

Publish when a meaningful customer-visible change is available. For frequent patch releases, group low-impact fixes into a regular digest if individual announcements would create noise. Do not wait so long that customers cannot connect a shipped improvement to the request or problem behind it.

Release Notes Template (Copy or Download)

Copy the complete release notes template

This markdown template covers a major release without requiring every section for every update. It follows the category convention documented by Keep a Changelog, then adds a plain-language summary, known issues, migration notes, and direct help links.

Keep only categories that contain useful information. Empty headings make a short update look unfinished and force readers to scan for content that is not there. A patch may use only the title, summary, Fixed, Known issues, and Links. A major release may need the complete structure.

Release notes markdown

# [Product name] [Version] - YYYY-MM-DD

> TL;DR: [Summarize the customer-visible value of this release in one sentence.]

## Added
- [New feature or capability, written in user-facing language.]

## Changed
- [Improvement to an existing behavior, workflow, or interface.]

## Fixed
- [Bug fix and the problem it resolves.]

## Deprecated
- [Feature or behavior that will be retired, including the replacement and timing.]

## Removed
- [Feature or behavior removed in this release, including the reason when useful.]

## Security
- [Security improvement, affected versions, and any action users should take.]

## Known issues
- [Known limitation, who it affects, and the available workaround.]

## Breaking changes and migration notes
- [Breaking change.]
- Migration: [Exact steps required before or after upgrading.]

## Links
- Documentation: [https://example.com/docs]
- Support: [https://example.com/support]

What each release note section is for

Version, date, and TL;DR

The header identifies the release unambiguously. Use the version customers see in the product, package, or app store, then use an ISO-style date so readers in different regions do not interpret it differently. If the product does not expose versions, use a release name with the date.

The one-line summary should state the main customer value. It is not a list of every change and should not repeat the release name. Write it so a reader can decide whether the rest matters: who can now do what, or which recurring problem is now resolved.

Added, Changed, and Fixed

Added contains capabilities that did not exist before. Changed covers an improvement or new behavior in something already available. Fixed identifies behavior that was wrong and now works as intended. These categories answer different reader questions, so resist putting every positive item under Added.

Begin each bullet with the user-visible outcome. Name the area of the product and the affected workflow. Link to documentation when a feature needs setup or deserves a full walkthrough. Internal issue IDs can follow at the end if the audience uses them, but they should not carry the explanation.

Deprecated and Removed

Deprecated means a feature still works but is scheduled to end. State the replacement, the expected timing, and the action a customer should take. Removed means the old behavior is no longer available in this release. Link back to the earlier warning and migration guidance when possible.

Do not hide a removal inside Changed. A reader scanning for risk should be able to find it immediately. If only a narrow audience is affected, name that audience. If no action is required, say so rather than leaving every customer to investigate.

Security and known issues

Security notes should provide enough information for a customer to judge exposure and act without publishing detail that creates new risk. Identify affected versions, the corrected version, and required actions. Coordinate sensitive disclosure through the appropriate security process before publishing.

Known issues protect readers from discovering a limitation alone. State the symptom, affected users or environments, and available workaround. Add the expected correction only when the team can maintain that commitment. Remove the item or link to its fix in a later release note.

Breaking changes, migration, documentation, and support

A breaking change means existing use may fail or behave differently without action. Name the old behavior, the new behavior, the affected audience, and the first version that requires the change. Migration notes should provide ordered, testable steps rather than a broad instruction to update.

Finish with the next destinations. Documentation explains setup and edge cases. Support handles account-specific problems. If the update has a public request or roadmap item, link that history so customers can connect the shipped result to the earlier need.

Filled release notes example

This fictional update shows how a product feedback tool might explain customer-visible value, a fix, a known issue, and one migration step without describing internal implementation work.

Northstar Feedback 2.8.0 - 2026-07-15

TL;DR: Board owners can now review demand faster with saved status filters and clearer voter context on every request.

Added

Saved filters for New, Considering, Planned, In Progress, and Done requests.
A voter-context panel that keeps the request, support count, and recent comments together.

Changed

Board statistics now use the same status labels as the public roadmap.

Fixed

Long request titles no longer cover the vote control on narrow mobile screens.

Known issues

Saved filters do not yet sync between browsers. Recreate a filter when working on a second device.

Breaking changes and migration notes

API clients that read the previous status label field must use the new status name field.
Migration: update the field mapping, run one request-list check, then deploy the client change.

Links

Documentation: northstar.example/docs/status-filters
Support: northstar.example/contact

Release notes variants

Major release

Keep the full template. Lead with the primary outcome, group features into a few useful themes, and include screenshots or short examples where the interface changed. Give breaking changes and migration their own prominent section near the top if readers must act before upgrading.

A major release may also need an overview page for the story and separate documentation for setup. The release notes should remain the scannable record of changes, risks, and next actions rather than becoming a complete product manual.

Minor or patch release

Remove empty categories. A minor release often needs Added, Changed, Fixed, and Links. A patch may need only a summary and Fixed. Keep Security, Known issues, or migration content whenever it applies, even if that makes a small release note longer.

Group several low-impact fixes into one note when the audience does not benefit from a separate announcement for each build. Still preserve version and date details so support can identify when a correction became available.

Mobile app store notes

App store space is limited and most readers scan quickly. Start with the top two or three benefits in plain language. Mention a critical fix or security action when relevant. Move detailed migration, known-issue, and support information to a linked page the team can update without waiting for store review.

Avoid a generic line that says only that bugs were fixed and performance improved. Name at least one workflow that became better. A short specific note is more useful than a polished message that tells the customer nothing.

Technical vs user-facing

Technical notes may include package names, endpoints, schema changes, compatibility, deprecation timing, and exact migration commands. User-facing notes should explain behavior, benefit, affected workflows, and actions in the reader's terms. The same release can have both documents linked from one version record.

Do not hide a breaking API change from technical readers or force general users through implementation detail. Split the audience when the information needs differ, then make the relationship between the two versions clear.

Edit release notes for decisions, not applause

Start each bullet with the changed outcome

A reader wants to know what is now possible, corrected, or required. Begin with that result, then add the feature name or implementation context. "Board owners can export a full year of requests in one CSV" is clearer than "Added asynchronous export processing" for a customer-facing note. The technical mechanism can live in linked documentation when it helps developers.

Use a verb that describes the reader's action or the product's behavior. Avoid announcing that the team worked hard, completed a project, or made improvements without identifying the result. Release notes document product change. They are more credible when the value is evident from specific behavior.

Keep one meaningful change in each bullet

A bullet that contains several unrelated changes is difficult to scan, link, and discuss with support. Split additions, behavior changes, and fixes when a reader might care about one but not the others. Keep related details together when separating them would hide the complete outcome, such as a new control and the permission needed to use it.

Group bullets under short themes when a release contains many items. Themes should reflect customer workflows or product areas, not internal squads. A customer looking for export changes should not need to know which engineering group owned the work.

Name the affected audience and required action

If a change applies only to administrators, mobile users, developers, or a particular workflow, say so at the beginning. Scope helps unaffected readers move on and helps affected readers recognize that the note deserves attention. Do not write "everyone" unless the product behavior genuinely changed for every reader.

Put required actions in direct language. State what to change, when to change it, and how to confirm success. If no action is required, say that in security, compatibility, or migration notes where a cautious reader might otherwise assume work is needed.

Link to depth without outsourcing the explanation

A release note should make sense before the reader follows a link. State the change and its consequence, then link to setup, reference, migration, or troubleshooting detail. "Learn more" is a weak destination label. Name what the reader will find, such as migration steps, API reference, or permission setup.

Check every link in the published environment and confirm that access matches the audience. A private project ticket is not useful evidence for a public release note. Keep a stable public destination for durable product behavior and use support for account-specific help.

Run a final release-note checklist

Confirm the version and date, remove empty categories, verify the summary against the actual release, and test every required action. Check that known issues name a workaround, removals point to earlier notice, and breaking changes include ordered migration steps. Ask support whether the note answers the first likely customer question.

Read the note once as a customer who did not attend the release meeting. Remove acronyms, internal project names, and passive phrases that hide who must act. Then compare the note with the product in production. The final copy should describe what the audience can use now, not what the team expected to deploy.

Cadence, editing, and announcement channels

Publish close enough to delivery that the note still has an owner and the details are accurate. Prepare the draft during release review, then confirm the final version, date, known issues, and links after deployment. Do not announce availability before the intended audience can actually use the change.

Assign one editor to make the voice consistent. Product and engineering should confirm behavior, support should test whether the explanation answers likely questions, and security should own sensitive disclosure. The editor removes internal shorthand and ensures every required action has a clear subject and sequence.

Use email for releases that matter broadly or require action. Use in-app messages for changes relevant to a workflow the reader is already using. Keep the durable release note at one URL so both channels can point to the same maintained source rather than creating several slightly different explanations.

When customers voted for the work, move the item to the shipped column and announce it through the same public roadmap workflow. That preserves the path from request to release. The audience receives an update because it expressed interest, not because the team reconstructed a contact list after shipping.

Review a final note on mobile as well as desktop. Keep headings descriptive, bullets short, and links specific. Readers should be able to identify the main value, any risk, and their next action without reading every sentence.

Browse the bug report template for a structured input to the fixes section, or return to all product team templates. FeatQ payment options are listed on the pricing page.

Release notes template