Release Notes Template

Use this template to communicate what changed, why it matters, and what users need to do. Pair it with the Changelog Template for tracking and the Post-Deployment Checklist for verification.

Overview

Release notes are the primary communication channel between the people who build software and the people who use it. Good release notes answer three questions: what changed, why it matters, and what do I need to do. Bad release notes dump a git log and leave users to figure it out.

This template covers:

1. Structured sections — highlights, breaking changes, new capabilities, fixes, security
2. Audience targeting — different tones for users, operators, and developers
3. Upgrade instructions — explicit steps, not assumptions
4. Known issues — transparency about what is not yet fixed
5. Semver alignment — matching notes to version bump type

Template

# Release vX.Y.Z — [Release Title]

**Release Date:** YYYY-MM-DD
**Status:** [draft / published / deprecated]

## Highlights
2-3 sentences summarizing the most important changes for users.

## Breaking Changes
- **Change:** Description of what changed
- **Impact:** Who is affected and how
- **Migration:** Exact steps to adapt

## New Capabilities
- **Capability name** — short description and link to docs

## Improvements
- **Area** — what got better and by how much

## Bug Fixes
- **Issue #123** — description of the fixed bug

## Security
- **CVE-YYYY-NNNN** — severity and fix summary

## Deprecations
- **Capability X** — will be removed in vX.Y+2.0; use Capability Y instead

## Upgrade Instructions
1. Step 1
2. Step 2
3. Verify with: `command to check`

## Known Issues
- **Issue #456** — workaround available, fix targeted for next release

## Full Changelog
Link to full commit diff or changelog file.

Filled Example

# Release v2.5.0 — CSV Export & Performance Improvements

**Release Date:** 2026-07-15
**Status:** published

## Highlights
Added CSV export for analytics dashboards. Improved dashboard load time by 40%.
Fixed a bug where date ranges crossing month boundaries produced empty exports.

## Breaking Changes
- **Change:** `/api/v1/reports` endpoint now returns `metadata` object instead of flat fields
- **Impact:** Any client parsing the response as flat JSON will break
- **Migration:** Update response parsing to read from `metadata` object. See migration guide.

## New Capabilities
- **CSV Export** — Export any dashboard chart as CSV. See [docs](/docs/csv-export).
- **Saved Filters** — Save and name dashboard filter presets for reuse.

## Improvements
- **Dashboard load time** — reduced from 3.2s to 1.9s (p95) by lazy-loading charts
- **API rate limits** — increased from 100 to 200 req/min for Pro tier

## Bug Fixes
- **Issue #234** — CSV export downloads empty file when date range crosses month boundary
- **Issue #231** — Saved filter names truncate at 20 characters
- **Issue #228** — Dashboard crashes when switching from table to bar chart with 0 rows

## Security
- **CVE-2026-1234** — XSS vulnerability in chart tooltip rendering (High). Fixed by escaping user input in tooltip templates.

## Deprecations
- **`/api/v1/reports` flat response format** — will be removed in v3.0.0. Use `metadata` object format. See [API Deprecation Notice](/docs/api/api-deprecation-notice-template).

## Upgrade Instructions
1. Update the SDK to v2.5.0: `npm install @stackpractices/sdk@2.5.0`
2. If using `/api/v1/reports`, update response parsing (see migration guide)
3. Verify: `curl -H "Authorization: Bearer $TOKEN" https://api.example.com/v1/reports | jq .metadata`

## Known Issues
- **Issue #240** — CSV export fails for charts with more than 10,000 rows. Workaround: narrow date range. Fix targeted for v2.5.1.

## Full Changelog
https://github.com/example/repo/compare/v2.4.1...v2.5.0

Audience-Specific Versions

Audience	Focus	Tone
End users	New capabilities and bug fixes that affect their workflow	Friendly, benefit-oriented
Operators	Breaking changes, upgrade steps, security fixes	Precise, action-oriented
Developers	API changes, deprecations, library updates	Technical, detailed

Semver Alignment

Version bump	When to use	Release notes focus
MAJOR (X.0.0)	Breaking changes	Migration guide, breaking changes section first
MINOR (X.Y.0)	New functionality, backward-compatible	New capabilities, improvements
PATCH (X.Y.Z)	Bug fixes, backward-compatible	Bug fixes, security patches

What Works

• Write release notes before the release — they are a forcing function for final review
• Highlight breaking changes first — users scan for things that might break them
• Include upgrade instructions — even for “no action required” releases, say so explicitly
• Link to documentation — every new capability should have a corresponding docs page. Link to the API Documentation Template for reference.
• Include verification commands — give users a way to confirm the upgrade worked
• Date every release — ISO 8601 format (YYYY-MM-DD) for consistency
• Link to full diff — let developers dig into the commit-level details if they want

Common Mistakes

• Listing every commit — users do not care about “refactor helper function”
• Omitting breaking changes — this breaks trust and causes incidents. See Incident Postmortem Template for recovery procedures.
• No upgrade instructions — users waste time guessing the migration path. See Environment Setup Guide for configuration context.
• Skipping known issues — transparency builds trust; hiding problems destroys it
• Vague descriptions like “various improvements” — name the improvement and quantify it
• No link to migration guide for breaking changes — users need a step-by-step path

Release Notes Example

=== Release Notes: v2.5.0 ===

# v2.5.0 - 2026-07-15

## New Features

- **Passkey authentication**: Users can now register and authenticate using
  passkeys (WebAuthn) in addition to passwords.
  Setup in Settings > Security > Passkeys.

- **CSV data export**: Administrators can export any table to CSV from
  the admin panel.

- **Multi-language support**: Added support for French and Portuguese.
  Total supported languages: 5 (EN, ES, FR, PT, DE).

## Improvements

- **Search performance**: Full-text search is now 3x faster thanks to
  migration to GIN indices in PostgreSQL.

- **Pagination**: Page limit increased from 50 to 200 results per page.

- **Structured logs**: All logs now use JSON format with correlation IDs
  to facilitate debugging.

## Bug Fixes

- **#456**: 500 error when creating account with email longer than 50 chars
- **#459**: Push notifications not sent on iOS 17.4+
- **#462**: Notification counter did not reset when all were read
- **#465**: Timestamps in API showed incorrect timezone

## Breaking Changes

- **API v1 deprecated**: API v1 will be removed in v3.0. Migrate to v2.
  Migration guide: docs/api-migration-v1-to-v2.md

- **user.name field removed**: Replaced by user.firstName and user.lastName.
  Clients using user.name will receive a 400 error.

## Security Notes

- Updated JWT library from 2.1.0 to 2.3.0 (CVE-2026-1234)
- Added origin validation to prevent CSRF on forms
- Automatic secret rotation every 90 days (configurable)

## Upgrade

  Docker: docker pull company/app:2.5.0
  npm: npm install company-app@2.5.0
  Helm: helm upgrade app company/app --version 2.5.0

## Release Metrics

  Commits: 47
  Contributors: 6
  Issues closed: 12
  PRs merged: 31
  Lines changed: +3,245 / -1,892

Variants

Automated release notes (release-please, semantic-release)

Tools like release-please and semantic-release generate release notes from conventional commit messages. Use commit prefixes (feat:, fix:, BREAKING CHANGE:) and the tool auto-generates categorized notes. Review and edit the output before publishing — automated notes are a starting point, not a finished product.

Internal service release notes

For internal services, add deployment context: which environments were updated, rollback procedure, feature flags enabled/disabled, and links to monitoring dashboards. Operators need to know what changed in their environment, not just what changed in the code.

Hotfix release notes

Hotfixes need a shorter format: “Fixed [bug] that caused [symptom]. Deployed to [environment]. Monitoring for [metric]. Rollback: [command].” No highlights or new capabilities — just the fix and the operational context.

Frequently Asked Questions

How detailed should release notes be for internal services?

Internal services need the same structure but with additional deployment context: which environments were updated, rollback procedure, and links to monitoring dashboards. See CI/CD Pipeline Guide for deployment automation.

Should I include CVE numbers for security fixes?

Yes, always. Security-conscious users need to cross-reference with their vulnerability scanners. Include the CVE, severity score, and a brief description of the attack vector.

Do patch releases (0.0.X) need full release notes?

Yes, but they can be shorter. A patch release note needs: “Fixed [bug] that caused [symptom]. Upgrade recommended. No breaking changes.”

Should release notes go in the repository or on a website?

Both. Keep a CHANGELOG.md in the repository for developers browsing the code. Publish release notes on a website or mailing list for users who do not read git repos. The website version can be more user-friendly; the CHANGELOG can be more technical.

How do I communicate release notes to users who do not read docs?

Use multiple channels: in-app notifications for breaking changes, email for major releases, and a Slack/Discord announcement for community projects. Do not rely on a single channel — users miss things.

What if a release introduces a regression?

Acknowledge it quickly. Add a “Known Issues” section to the release notes with the regression, a workaround if available, and a target fix version. If the regression is severe, consider pulling the release and re-publishing once fixed.

How do we decide what to include in release notes?

Include: new features (with usage instructions), notable improvements (with user impact), bug fixes (with issue number), breaking changes (with migration instructions), and security notes (with CVEs if applicable). Do not include: internal refactoring with no user impact, dependency updates with no behavior change, or typo fixes. For breaking changes: include a before/after code example. For features: include a screenshot or GIF if there are UI changes. Keep the language accessible — users are not engineers. If a feature requires configuration: include the steps.

How often should we publish release notes?

Publish release notes with every release. For frequent (continuous) releases: publish weekly or per-sprint notes with a summary of changes. For semver releases: publish notes per version (v2.5.0, v2.5.1, etc.). For hotfixes: publish notes with the fix and the reason. Maintain a CHANGELOG.md file with all historical release notes. Use a consistent format so users can scan quickly. For open source projects: publish notes on GitHub Releases in addition to CHANGELOG. Release notes are the most important communication with your users — do not treat them as an afterthought.

How do we automate release notes generation?

Use conventional commits (feat:, fix:, breaking:) so release notes can be auto-generated. Tools like semantic-release, changesets, or release-please can generate notes from commits. Configure CI so each PR adds a CHANGELOG entry. Use GitHub Releases with auto-generated release notes. For more control: use a release notes template and fill it manually with the most important changes. Automate routine notes (dependencies, typos) and manually write important notes (features, breaking changes). Automation reduces work but does not replace human judgment on what matters.

End of document. Review and update quarterly.