Release Notes
/ Template Pack.
Three formats — technical changelog, marketing blog, in-app announcement — with worked examples for every release type.
Version: ______
Date: ______
The three audiences
Release notes fail when they’re written for one audience and broadcast to all three. Developers want changelog precision — what changed, what broke, what to migrate. Customers want value/benefit framing — why this matters and how their work gets easier. In-app readers want brevity — one line of value, one CTA, no scroll. The same release usually deserves all three formats; the same words almost never do. The format pack below treats each as a first-class artifact.
Format 1: Technical Changelog
Versioned, dated, sectioned. Read by integrators, devs, and the AE who needs to answer “does this break anything?” in a deal. Use Keep-a-Changelog conventions: Added / Changed / Fixed / Deprecated / Removed / Security. Every line names the surface, not the internal module.
- Smart Search v2 with semantic matching and typo tolerance on the global search bar.
- Recent-search dropdown (last 5 per user, pinnable up to 3).
- Idempotency-Key header support on POST /v1/events; required from v4.0.0.
- Search results now sort by relevance score; previous behavior (created_at desc) available via &sort=recent.
- Webhook retry policy: exponential backoff 1s → 60s → 1h, 5 attempts max.
- CSV export no longer drops UTF-8 BOM, preventing Excel mojibake on non-ASCII fields.
- Bulk delete undo window extended to 30s (was 10s and inconsistent across tabs).
- GET /v1/search?q= without Accept-Version header. Returns v1 results until 2026-08-01, then 410.
- Legacy /v0/* endpoints (deprecated 2025-09-01).
- Magic-link tokens are now scoped to originating IP/device fingerprint; mismatches require confirmation.
Format 2: Marketing Blog Post
Structure: hero promise · what shipped · why it matters · who it’s for · how to use · what’s next. Same release as the changelog, framed for the customer who reads the blog because they got the in-app card.
Posted 9 May 2026 · 3 min read
The global search bar now understands intent, not just keystrokes. Type “invocies last week” and it finds the invoices, the typo, and filters by the date. Recent searches surface the moment you focus the bar. Filters compose without the page reload.
Across our customer base, search-to-action was the single biggest drop-off in activation — 60% of new users gave up because they couldn’t find what they remembered. Smart Search v2 closes that gap. Internal benchmarks show a 17-point lift in successful searches per session.
Everyone with a workspace bigger than 50 records. If you’ve ever used Cmd-F to find a thing you knew existed: this is for you.
Hit / from anywhere. Start typing. The dropdown shows recent searches first, then live results. Up/down arrows to navigate, Enter to open. Pin a search by clicking the pin icon — it stays in your dropdown.
Saved searches and shareable views ship in v3.5 (June). Voice search is on the radar but not committed.
Format 3: In-App Announcement
One-line headline. One- to two-sentence body. Single CTA. The reader has 4 seconds before they dismiss; design for that.
X-Idempotency-Key header.Worked example: feature ship (all 3 formats)
The Smart Search release above is the worked example. Same content, three voices — precision for devs, value for customers, brevity in-app. Notice that the changelog says “sort by relevance, &sort=recent for legacy”; the blog says “finds what you meant”; the in-app card says “Try it”. None of them are wrong. None of them are interchangeable.
Worked example: fix-only release
Fix-only releases are often skipped because “there’s no story.” That’s wrong. Customers who hit the bug deserve a note; customers who didn’t deserve to know you’re shipping. Skip the blog. Ship the changelog and a targeted in-app card.
- Slack notifications stopped firing for users in the “Watcher” role on shared boards.
- SSO redirect loop on accounts with email aliases that resolved to two IdP records.
- Decimal precision in numeric exports: trailing zeros are preserved for currency columns.
- Patched CVE-2026-0518 in upstream PDF rendering library; no exploit observed in our environment.
Targeted card. Targeted audience. The 99% of users who didn’t hit it never see the card; the 1% who did see acknowledgement, not a generic “improvements” post.
Worked example: major upgrade
Major upgrades = breaking changes, deprecations, or migration paths. The blog leads with what’s changing for the reader, then a clear migration window. The changelog spells out exact endpoints. The in-app card warns affected users only.
- GET /v1/search without Accept-Version header now returns 410. Use Accept-Version: 2 for current behavior.
- Legacy /v0/* endpoints removed entirely (deprecated since 2025-09-01).
- POST /v1/events now requires Idempotency-Key. Requests without it return 422.
- Webhook payload version bumped to 2.0. Subscribe to webhook.v1 explicitly to keep old shape until 2026-12-31.
The blog version of this opens with: “v4.0.0 ships August 1. Three changes affect integrations — here’s the 5-minute migration guide.” No customer reads “breaking changes” at the top of a post and feels good. Lead with the timeline and the path forward, not the apology.
Frequency rules
- Weekly changelog — ship every Friday whether or not anything “big” landed. Devs and integrators expect a heartbeat.
- Monthly blog — bundle the marketing-worthy items. If you can’t name three customer-facing wins in a month, write nothing — don’t pad.
- In-app on opt-in — show only to users who would care. A user who never touched search shouldn’t see the search-fix card.
5 release-notes anti-patterns
- “Many bug fixes and improvements.” Says nothing, signals nothing, builds no trust. Replace with named fixes — even three is enough.
- Marketing language in the changelog. “Reimagined search experience” in a dev doc is a tax on the reader. Move it to the blog.
- Internal jargon. “Migrated SearchService to v4 controller” tells the customer nothing. They want to know what changes for them.
- Hidden breaking changes. Burying a deprecation under “Improvements” loses your integrator’s trust permanently. Lead with it.
- No timestamp. A changelog entry without a date is unverifiable history. Always version, always date.
Generating these from your tracker
The bottleneck is rarely the format — it’s the time to compile what shipped, who it affects, and how to phrase it three ways. MindBacklog’s release-notes generator pulls completed work from your tracker and drafts these formats, so the PM edits instead of starting blank. Whether you use it or not, the rule holds: write all three, ship them on a cadence, and never write “and other improvements” again.