slice icon Context Slice

Changelog Template

# [Product Name] Release Notes

## [Version X.Y.Z] - [Date]

### New
- **[Feature Name]:** [One sentence describing what users can now do. Focus on benefit, not implementation.]
- **[Feature Name]:** [Description]

### Improved
- **[Area]:** [What got better and why it matters]
- **[Area]:** [Description]

### Fixed
- Fixed an issue where [specific problem] when [specific condition]
- Resolved [bug description]

### Changed
- [Breaking change or significant behavior change with migration guidance if needed]

---

## [Version X.Y.Z-1] - [Previous Date]
...

Style Guidelines

Tone

  • Friendly but professional — Not robotic, not overly casual
  • User-focused — "You can now..." not "We implemented..."
  • Clear — No jargon unless your users expect it

Structure

  • New: Genuinely new capabilities
  • Improved: Enhancements to existing features
  • Fixed: Bug fixes (be specific about what was wrong)
  • Changed: Breaking changes or significant behavior shifts

Writing Patterns

Good:

Smart Search: Find emails faster with natural language queries. Just type what you're looking for—"invoices from last month" or "messages from Sarah about the project"—and get relevant results instantly.

Bad:

Added new search functionality with NLP capabilities for improved query processing.

Good:

Fixed an issue where notifications weren't delivered when the app was in the background on iOS 17.

Bad:

Fixed notification bug.

Required Inputs

Before writing a changelog, gather:

  1. Version number — Following semver (X.Y.Z) or your versioning scheme
  2. Release date — When this ships
  3. List of changes — From tickets, PRs, or release checklist
  4. Audience — End users? Developers? Internal teams?

Version Numbering

Follow semantic versioning (MAJOR.MINOR.PATCH) unless the product has an existing scheme:

Change Type Version Bump Example
Breaking changes, major redesigns, backward-incompatible API changes MAJOR (X.0.0) API v2, complete UI overhaul, removed features
New features, significant improvements, new endpoints MINOR (0.X.0) New search, dashboard additions, new API methods
Bug fixes, minor improvements, patches PATCH (0.0.X) Performance fix, typo correction, security patch

Decision guide: If users need to change their behavior or update their code, it's at least MINOR. If integrations might break or workflows need updating, it's MAJOR.

Pre-release versions: Use suffixes for beta or preview releases: 2.0.0-beta.1, 1.5.0-rc.1.

When unsure: Ask what changed. New capability = MINOR. Fix to existing capability = PATCH. "This might break things" = MAJOR.

Audience Variations

For End Users

  • Focus on benefits and outcomes
  • Avoid technical details
  • Use simple language
  • Include visuals if helpful

For Developers

  • Include API changes
  • Note deprecations with timeline
  • Link to migration guides
  • Be technically precise

For Internal Teams (Sales/Support)

  • Highlight customer-facing changes
  • Include talk tracks for new features
  • Note known limitations
  • Provide FAQ answers

Grouping Changes

When there are many changes, consider grouping by area:

### New

**Collaboration**
- Real-time cursor presence shows who's viewing the document
- Comment threads now support @mentions

**Search**
- Natural language search understands conversational queries
- Search results now show preview snippets

What to Omit

  • Internal refactoring (unless it affects performance users notice)
  • Security fixes (mention "security improvements" without details)
  • Minor UI tweaks (unless specifically requested by users)
  • Changes still behind feature flags