Release Notes Template

Use this template to communicate what changed, why it matters, and what users need to do.

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 Features
- **Feature 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
- **Feature X** — will be removed in vX.Y+2.0; use Feature 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.

Audience-Specific Versions

Audience	Focus	Tone
End users	New features 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

Best Practices

• 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 feature should have a corresponding docs page

Common Mistakes

• Listing every commit — users do not care about “refactor helper function”
• Omitting breaking changes — this breaks trust and causes incidents
• No upgrade instructions — users waste time guessing the migration path
• Skipping known issues — transparency builds trust; hiding problems destroys it

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.

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.”