Prd V08 Changelog As Marketing

Changelog as Marketing

Position in workflow: v0.8 Release Planning → v0.8 Changelog as Marketing → v0.9 Launch Channels (ORB)

Execution Mode

Default is standard. See .claude/rules/08-skill-execution-modes.md for selection logic.

What This Does

Treats the changelog as a distribution surface, not an engineering record. Each shipped release becomes a content artifact that lands across Owned and Rented channels with minimal extra effort. This is the bridge between v0.8 (what shipped) and v0.9 (where it gets told).

Done well, this is one of the highest-leverage Owned-channel investments — Stripe, Linear, Vercel, and Sentry have shown that an opinionated changelog drives ongoing inbound that compounds over years. Done badly, it's a dumping ground for "fixed bug X" that nobody reads.

How It Works

1. Define the changelog audience(s) — Engineering changelogs (for users running self-hosted or integrating an API), customer-facing changelogs (for end-users), and internal changelogs (for the team) have different shapes. Anchor to the Positioning best-fit segment.
2. Categorize release content — Each shipped item gets a category:
   • New feature (publish loudly)
   • Improvement (publish, briefly)
   • Breaking change (publish, prominently, with migration path)
   • Deprecation (publish, with timeline)
   • Fix (publish only if user-visible)
   • Internal (don't publish externally)
3. Map categories to channels — Each category gets a channel destination from the ORB mix:
   • New feature → Blog post + email + Twitter + LinkedIn
   • Breaking change → Email (high-priority) + RSS + blog
   • Improvement → Blog (digest) + Twitter (digest)
   • Fix → Changelog page only
4. Build per-channel format templates — Each channel has a length/tone constraint:
   • Email: subject line + 2-paragraph body + CTA
   • Blog: full writeup, screenshots, code samples
   • Twitter/X: 280 chars, one image
   • LinkedIn: 1,000-1,500 chars, professional voice
   • Slack/Discord: short with link to blog
   • RSS: full content for engineering audiences
5. Set publish cadence — Per-release (every shipped release publishes immediately) vs. digest (weekly/monthly roll-up). Most teams need both: per-release for big things, digest for the rest.
6. Plan attribution — Every channel-published release gets a UTM. Track changelog → signup conversion to identify which categories convert.

Example

A developer-tools product ships:

Tuesday publish:

• Blog post: "Webhooks v2 is live — here's what changed and how to migrate"
• Email to API customers (segment-targeted, not full list): "Action needed: webhook v1 sunset"
• Twitter: "Webhooks v2 ships today. v1 is sunset in 6 months. Migration guide: [link]"
• Changelog page: all five items (including the fix and internal note marked appropriately)

What You Get Back

• MON-CHG-* changelog entries (one per shipped release) — Master record with category, audience, channel mapping, links to per-channel publications
• GTM-CHG-* per-channel formats (one per channel) — Templates and example content
• Publish cadence schedule — Per-release vs. digest decisions
• KPI attribution plan — UTMs and conversion tracking

When to Use It

Consumes

• DEP-* release entries (from v0.8 Release Planning) — What's being released, when
• FEA-* features (from v0.3) — What new features exist; categorization input
• GTM-* channel mix (from v0.9 Launch Channels ORB, when available) — Where to publish
• GTM-* positioning (from v0.9 Positioning, when available) — Voice and tone constraints
• PER-* best-fit characteristics — Audience tone calibration
• KPI-* baselines — Attribution targets

When this skill runs before v0.9 has executed, channel mapping uses placeholder channels and is reconciled when v0.9 channels are finalized.

Produces

• MON-CHG-* entries in SoT/SoT.DEPLOYMENT.md (or a dedicated SoT/SoT.CHANGELOG.md if release volume warrants)
• GTM-CHG-* entries with Type=Channel-Changelog (per-channel format templates)
• CFD-* gaps surfaced — If a release category lacks an obvious channel mapping, log as research gap

Output Template

Copy code
MON-CHG-XXX: Release — [Release name / version]
Type: Changelog
Date: YYYY-MM-DD
Owner: [Person / role]
Status: [Drafted | Reviewed | Published]

Released items:
  - [Item 1] — Category: [New feature | Improvement | Breaking change | Deprecation | Fix | Internal]
  - [Item 2] — Category: ...

Audience: [API customers | All users | Internal team | Mixed]

Channel publications:
  - Blog: [URL or "scheduled YYYY-MM-DD"]
  - Email: [Segment + scheduled date]
  - Twitter: [Scheduled date]
  - LinkedIn: [Scheduled date]
  - Changelog page: [Updated YYYY-MM-DD]

Attribution: utm_campaign=changelog-<version>

Linked IDs: DEP-AAA (release), FEA-BBB (features shipped), GTM-CHG-CCC (channel formats), KPI-DDD (attribution)

Copy code
GTM-CHG-XXX: Channel Format — [Channel name]
Type: Channel-Changelog
Channel: [Blog | Email | Twitter | LinkedIn | RSS | Slack]
Owner: [Person / role]

Format constraints:
  Length: [chars / words / sections]
  Tone: [Conversational | Technical | Formal — anchored in Positioning voice]
  Visuals: [Required / optional]
  CTA: [Specific action expected]

Template:
  [Reusable template for this channel, with variable placeholders]

Example (most recent use):
  [Concrete example from MON-CHG-XXX]

Publish trigger: [Per-release | Weekly digest | Monthly digest]

Linked IDs: MON-CHG-AAA (latest use), GTM-YYY (positioning voice)

Anti-Patterns

Quality Gates

Before publishing the first release:

• Audience(s) defined (engineering, customer-facing, internal — separately if needed)
• Categorization scheme exists (at minimum: new / improvement / breaking / fix)
• Channel mapping table exists (categories → channels)
• Per-channel format templates exist
• Publish cadence committed
• Attribution plan (UTM convention) defined
• Voice/tone honors GTM- positioning (if v0.9 is done)

Downstream Connections

Detailed References

• Stripe changelog: stripe.com/changelog — the canonical example
• Linear changelog: linear.app/changelog — opinionated voice
• Vercel changelog: vercel.com/changelog — visual-heavy
• jonathimer's changelog-updates skill (devmarketing-skills)
• (No bundled references/ — read the source examples for current best practice)