Writing Release Notes

Overview

Summarize shipped changes in a way that is accurate, scannable, and appropriate for the intended audience (internal, customers, or both).

When to Use

• A set of PRs/issues is ready for release and needs a coherent summary
• Stakeholders need to know impact, risk, and required follow-ups
• You must communicate changes without leaking sensitive/internal details

When NOT to use

• No user-visible or operationally relevant changes occurred

Core Pattern

Write for outcomes, not implementation:

• What changed (user-facing)
• Who is affected (segments, plans, roles)
• Anything required (migration steps, toggles, downtime)
• Known issues (if applicable)