Release Notes template thumbnail

SOFTWARE ENGINEERING TEMPLATE

Release Notes Template

User-facing release notes covering features, improvements, fixes, breaking changes, and upgrade guidance.

Use this template

What's inside

Field

Details

Version

X.Y.Z

Release Date

Release Type

Minor

Release Manager

Name

Highlights

The big picture: what is the most exciting thing in this release and why should users care? Write this as if you are telling a colleague over coffee, not filing a report.

  • Headline feature or improvement — one sentence on what it does and why it matters

  • Second most notable change

  • Third, if there is one

New Features

[Feature Name]

Describe what the feature does from the user's perspective. Lead with the benefit, not the implementation. If there is a screenshot or GIF that shows it in action, include it.

  • Key capability 1

  • Key capability 2

  • How to access: where to find it in the UI, or the API endpoint / CLI command

[Feature Name]

Describe the feature. What problem does it solve?

  • Key capability

  • How to access

Improvements

Changes to existing features that make them better — faster, easier to use, more reliable. These are not new capabilities, but meaningful upgrades to things users already use.

  • Improvement: what changed and the user-visible effect (e.g., "Dashboard loads 3x faster on large workspaces")

  • Improvement: describe the change and the benefit

  • Improvement: describe the change and the benefit

Bug Fixes

  • Fixed: describe the bug from the user's perspective (e.g., "Fixed an issue where exported CSV files had incorrect timestamps for users in non-UTC timezones")

  • Fixed: describe the bug

  • Fixed: describe the bug

Breaking Changes

[Breaking Change Title]

What changed and why. Be direct about the impact — what will break if the user does nothing?

What you need to do:

# Before (old behavior)
old-command --old-flag

# After (new behavior)
new-command --new-flag

Delete this section if there are no breaking changes in this release.

Deprecations

Features or APIs that still work but are scheduled for removal. Users should begin migrating.

What

Replacement

Removal Date

Migration Guide

Feature or API being deprecated

What to use instead

Link to migration docs

Delete this section if nothing is being deprecated.

Known Issues

Issues we are aware of but have not fixed in this release. Being transparent about known issues builds trust.

Issue

Impact

Workaround

Fix Expected

Describe the issue

Who is affected and how

Temporary workaround, if any

Next release / specific date

Delete this section if there are no known issues.

Upgrade Notes

Steps to upgrade to this version. Include anything beyond the standard upgrade process.

  • Minimum required version to upgrade from (e.g., "Upgrade to v2.3 before upgrading to v3.0")

  • Database migrations: automatic or manual? Expected downtime?

  • Configuration changes: new environment variables, changed defaults, removed options

  • Dependency updates: anything the user needs to update on their end

Delete this section if the upgrade is straightforward with no special steps.

Thank You

Thanks to everyone who contributed to this release — whether through code, bug reports, feedback, or design. Special thanks to:

  • Contributors and community members who helped

Other Engineering templates