ContextQMD
Back to Paperclip

Release Announcement

packages/skills-catalog/catalog/optional/content/release-announcement/SKILL.md

2026.529.03.9 KB
Original Source

Release Announcement

Write the channel-appropriate announcement for a release without churn. Different surfaces need different shapes: a changelog entry is not a blog post is not a social card. The bar is: a reader of the chosen surface can decide in under 30 seconds whether this release affects them, and if so what to do.

When to use

  • A version, feature, or fix is shipping and needs writeup for at least one surface.
  • A previously private feature is going GA.
  • A breaking change needs broadcast before users hit it.

When not to use

  • An internal-only change with no user impact. Update internal docs; do not announce.
  • The release is incomplete (still in active development). Wait until it ships, even if marketing wants the post.

Determine the audience and channel first

AudienceBest channelTone
Existing power usersChangelog, in-app noteTerse, factual, links
Engineering teams adopting your APIRelease notes, dev blogExamples, migration steps, version pins
Prospective customersLanding page, marketing blogStory arc, problem → solution, social proof
Broad audienceSocial post, email newsletterOne-sentence pitch, link to depth
Internal teamSlack/Discord postWhat changed, who to ping if it breaks

Pick the audience for this writeup. One release often needs several writeups; do not blend them.

Universal structure

Whatever the channel, lead with:

  1. What changed. One sentence in the user's vocabulary.
  2. Who it affects. Which user role / use case.
  3. What to do. Migrate now / opt-in / no action needed.

Everything else is depth that supports those three.

Channel templates

Changelog entry (terse)

md
## v1.42.0 — 2026-05-26

### Added
- <feature> — <one-line user benefit>. ([#1234](link))

### Changed
- <change> — <one-line impact>. ([#1235](link))

### Fixed
- <bug> — <one-line user-visible symptom>. ([#1236](link))

### Deprecated
- <thing>. Replaced by <thing>. Removal planned for v<x>.

### Breaking
- <change>. **Migration:** <one-line> or <link to guide>.

Release notes (for adopters)

Same as changelog, plus:

  • Migration guide section with before/after code.
  • Compatibility table (versions, runtimes, OS).
  • Known issues and workarounds.
  • Acknowledgements (contributors, reporters of fixed bugs).

Dev blog post (300–800 words)

  • Hook (1 paragraph): the problem the release solves, in a real-world scenario.
  • What's new (3–5 bullets with sub-paragraphs): features, with one code or screenshot example each.
  • Upgrade (1 paragraph): how to upgrade, what to check.
  • What's next: one sentence about the next direction. Avoid promises.

In-app note

  • 1 sentence.
  • 1 link.
  • Dismiss after seen.

Social post

  • 1 sentence pitch.
  • 1 link.
  • 1 image or short clip.
  • No threadbait. If it needs a thread, write a blog post instead.

Writing rules

  • Lead with the user, not the team. You can now export to CSV beats We've added CSV export.
  • Numbers beat adjectives. 60% faster cold start beats much faster. Cite the methodology.
  • Show, don't just tell. One code snippet, one screenshot — more is noise.
  • Date the post. Undated release content rots fastest.
  • Link the migration path explicitly. Do not bury it.
  • Mark breaking changes with **Breaking:** prefix. Repeat in the email/social channel.

Avoid

  • "We are excited to announce" filler.
  • Lists of changes that mix user-visible and internal items.
  • Marketing claims without a way to verify.
  • Promised dates for unshipped work.
  • Pre-announcing something the team has not yet committed to ship.

Post-publish checklist

  • Changelog is in source control alongside the release.
  • Blog post date matches actual ship date.
  • All links work (release tag, PRs, docs sections).
  • Breaking changes are also in the upgrade guide, not only the post.
  • Internal team is notified before the public post goes live, not after.