Skip to content

Release Notes

A user-facing summary of what changed in a release and why it matters to the reader.

Release notes are the user-facing companion to every software release. Where a changelog records every commit, ticket, and patch for developers, release notes are written for the people who use the product - they ask “what does this mean for me?” before they ask “what changed?” A release note leads with the benefit, groups changes by theme or workflow area, and translates technical fixes into plain language. “Fixed a null reference in the auth service” becomes “you will no longer be logged out unexpectedly while editing.” The translation is the work.

The format earns its place by bridging the gap between the team that builds and the audience that uses. Most teams ship more changes than users can absorb; curation is therefore a core responsibility. Release notes decide what rises to the surface - what is worth the reader’s attention - and what stays in the commit log. A well-curated set of release notes respects the reader’s time and builds confidence that the product is improving in ways that matter to them.

# [Product Name] [Version] - [Release Date]
## [Optional headline capturing the theme of this release]
## What's new
- [Feature name]: [Plain-language description of the feature and what it enables for the user.]
## Improvements
- [Area or workflow]: [What improved and how the user notices the difference.]
## Fixes
- [Symptom or affected workflow]: [What was happening and that it no longer happens.]
## Known issues
- [Issue]: [Workaround if available.]
## Deprecations and breaking changes (if any)
- [What is changing]: [What the user must do, and by when.]

Announcing a versioned software release to end users or customers, publishing updates to a SaaS product, mobile app, developer tool, or library, communicating what changed in a public API or SDK, accompanying a plugin or package release to a marketplace or registry, notifying users of a breaking change or deprecation that requires action.

Documenting internal engineering decisions or architecture changes (use an ADR), recording every commit and merged pull request as a developer audit trail (use a changelog entry), promoting a new product or major version in narrative form to prospective customers (use a blog post or launch announcement).

product-thinker, technical-writer, friendly-mentor, encouraging, matter-of-fact, layered-disclosure

changelog-entry: A changelog is a chronological, exhaustive record of every change merged into a codebase, authored for developers rather than users. Release notes curate from the changelog: they select the changes worth communicating, translate them into user language, and lead with benefit rather than implementation detail.

blog-post-long-form: A long-form blog post tells a narrative story about why something was built, what problems it solves, and where the product is going. Release notes are not storytelling - they are scannable reference documents. Where a blog post invites reading, release notes invite scanning.

announcement: Release notes are version-anchored, multi-item, and curated from a changelog into scannable grouped sections (New, Improved, Fixed) under a version identifier. An announcement is a single-subject news message in the organization’s own voice with no version identifier and no grouped change sections. Use release notes when a versioned release has multiple changes to communicate; use an announcement when a single piece of news warrants its own direct message to the audience.

  • Opens with a version identifier and optional release date, not a prose introduction
  • Groups changes by what users notice (New, Improved, Fixed) rather than by engineering area or ticket
  • Each item leads with the user benefit or observable symptom, not with an internal ticket or PR number
  • Plain-language translation of technical fixes into user-facing behavior
  • Curates rather than enumerates - fewer items, higher signal per item
  • Second-person framing addresses the reader directly: You can now, or Exporting a report no longer
  • Breaking changes or deprecations isolated in a dedicated, visually distinct section
  • Bullet-pointing every commit or ticket rather than curating the changes that matter to users - Readers cannot determine what is worth their attention when everything is listed; curation is the core responsibility of this format.
  • Writing in technical jargon without translating into user-facing language - Resolved NullPointerException in TokenRefreshService is a changelog line; You will no longer be signed out while refreshing a shared link is a release note.
  • Burying breaking changes inside a routine fix list without a migration path - Breaking changes require action from the user; making them hard to spot leaves users stranded at upgrade time.
  • Framing the notes as a narrative story about why features were built rather than what changed and what it means - That is the confusable blog-post-long-form format; release notes are scannable reference documents, not product storytelling.
  • Benefit-framing tips into promotional hyperbole - every fix becomes a “major improvement” and every feature is “game-changing,” so the notes read as marketing copy rather than honest change documentation - Check that each item describes a specific, observable change in behavior. Reports now load in under 2 seconds on datasets over 50,000 rows is a release note; Experience blazing-fast performance is marketing copy.
  • Curation tips into omission - only the most dramatic changes appear, routine fixes vanish entirely, and users who encountered the omitted bugs feel unacknowledged and distrust the notes - Include all user-visible fixes, even minor ones. A short, undramatic note signals attentiveness. Reserve omission for changes that are genuinely invisible to users.
  • Plain-language translation strips out specificity until nothing is actionable - Various performance improvements and Bug fixes appear as entries that cover everything but inform nothing - Every item should name a specific workflow, area, or symptom. If a note cannot be more specific than Bug fixes, the change was not user-visible and belongs in the changelog, not here.
Write as release notes for a user-facing software release. Lead every item with the user benefit
or observable change, not the internal implementation detail. Group changes by what users notice -
new capabilities, improvements, fixes - not by engineering area, file, or ticket number. Translate
technical language into plain user-facing descriptions: resolved NullPointerException in
TokenRefreshService becomes you will no longer be signed out while refreshing a shared link.
Curate: include only changes that are visible or meaningful to the reader; leave exhaustive
enumeration to the changelog. For breaking changes or deprecations, call them out in a visually
distinct section and name the required user action. Keep the format scannable - version identifier,
grouped bullets, plain language. Do not write prose paragraphs in place of bullets. Do not use
marketing superlatives. Each item should describe a specific, observable change in user behavior
or capability.

See the Release Notes template.

Product Thinker, Technical Writer, Friendly Mentor, Encouraging, Matter of Fact, Layered Disclosure

Confessional, Skeptical, Reverent

Changelog Entry, Blog Post (Long Form), Announcement

Async-first standups for a distributed team

  • Async daily updates in #team-standup: You post to the channel by 10am your local time using the three-field template. No call. No round-robin. No status you have to repeat to people who already knew.

  • /standup Slack shortcut: Type /standup in any Slack message box to load the three-field template pre-filled with the Shipped / In progress / Blocked or at risk fields. The shortcut is also pinned in the channel description.

  • Thursday working session: A 60-minute real-time session at 8am Pacific / 8:30pm IST replaces the former sync standup slot. Use it for discussions that require live exchange. Agenda lives in docs/thursday-agenda.md. If nothing needs real-time discussion, the session cancels by Wednesday 5pm Pacific.

  • On-call triage role: The on-call engineer reads #team-standup between 10am and 11am Pacific each day and makes sure every @mention in a blocked item gets a substantive reply within the workday.

  • IST-compatible schedule: Engineers in India can participate at 10am IST rather than 9:30pm. The format applies the same participation standard to every timezone.

  • Blockers route directly: When you flag a blocker with an @mention, the person who can resolve it sees it in their Slack notifications immediately rather than waiting until the next meeting window.

  • Persistent, searchable history: Status updates live in Slack. Prior blockers, resolved dependencies, and completed work are searchable after the update window closes. The sync standup produced no persistent record.

  • Low-signal meeting time recovered: The 14-minute daily call averaged roughly 4 minutes of content that changed anyone’s behavior. The remaining time was status that required no response. That time is now yours.
  • Sync standup removed from calendar: The recurring 9am Pacific meeting is cancelled. Remove it from your calendar. The Thursday working session is the only team-wide synchronous slot going forward.
  • Post length: The three-field format is meant to be skimmed in under 60 seconds per teammate. If you find yourself writing paragraphs, trim to bullets. Pinned examples in #team-standup show the target length.

This release runs on a 30-day trial. Drop feedback in docs/trial-retro.md at any point. The Day 30 retro will decide whether v2.0 becomes permanent or reverts to the sync format.