write-release-note

Write Release Note

Write concise, user-focused release notes that communicate value and impact, not implementation details.

Why This Is Best Practice

Adopted by: Stripe (benchmark for developer communication), GitHub (model for technical release notes), Apple App Store (mandated format for consumer apps) Impact: Stripe's documentation is cited as the industry standard for developer experience; well-written release notes reduce support ticket volume by 15-25% after major releases (per Intercom product research).

Why best: Release notes are a product communication artifact, not a technical log. Users care about what changed for them, not how it was implemented. Stripe's impact-first pattern ("You can now do X") and GitHub's contextual notes (linking to docs for complex changes) set the bar for technical audiences.

Steps

1. Lead with user benefit — Start with what users can now do or no longer need to worry about. Not "Refactored auth module" but "Login is now 40% faster and supports passkeys."
2. Group by impact type — Use consistent categories: New, Improved, Fixed, Security, Breaking Changes. Order: New → Improved → Fixed → Security → Breaking.
3. Write one sentence per item — State the change and its user impact. Link to documentation for anything requiring more than one sentence.
4. Highlight breaking changes prominently — Use a visible header or warning; describe what breaks and provide the migration path or link to the migration guide.
5. Target the right audience — Developer-facing APIs: include code examples for breaking changes. Consumer apps: plain language, no jargon, benefit-oriented.
6. Include version and date — Always: version number, release date, and relevant links (full changelog, migration guide, docs).
7. Review for jargon — Read as a non-expert user; replace internal terms with plain language equivalents.

Rules

• Every breaking change must be explicitly labeled and include a migration path.
• Security fixes must be included; describe the class of vulnerability (not the exploit detail) and advise users to upgrade.
• Omit implementation details (refactors, dependency bumps, internal tooling) unless they affect users.
• Use present or future tense for new features ("You can now..."), past tense for fixes ("Fixed an issue where...").

Examples

Good (Stripe-style):

New: Webhooks now support retry configuration. You can set custom retry intervals and maximum attempts per endpoint in the Dashboard or via API.

Fixed: The invoice PDF download failed for invoices with non-ASCII characters in the customer name. This is now resolved.

Breaking: The charge.create endpoint no longer accepts source as a bare card object. Pass a PaymentMethod ID instead. [Migration guide →]

Common Mistakes

• "Various bug fixes and performance improvements" — tells users nothing; enumerate specific fixes.
• Commit message verbatim — developer-oriented messages lack context for users.
• Omitting the "so what" — "Added retry logic" → who cares; "Failed webhook deliveries are now retried automatically for 72 hours" → clear user value.

When NOT to Use

• When the release contains only internal refactors, dependency upgrades, or infrastructure changes that have no observable effect on user behavior, publishing a release note creates noise without informing any user decision.
• When the change is a hotfix for an actively exploited security vulnerability, publish a minimal security advisory through your coordinated disclosure process instead of a detailed release note that could aid attackers before users patch.
• When the audience is exclusively internal engineering teams consuming an internal library with no external contract, a commit log or internal Slack post is sufficient; a polished user-facing release note format is mismatched to the audience.