What format and structure should I use for changelogs?

Use the Keep a Changelog format, which includes an Unreleased section, dated version entries, and categories for Added, Changed, Deprecated, Removed, Fixed, and Security. Entries should be specific (e.g., stating percentage improvements rather than vague claims) and include links to docs or migration guides where relevant.

What types of changes should I include in a changelog versus skip?

Always include API and SDK changes, breaking changes, and security fixes. Consider including performance improvements, developer-experience changes, and infrastructure updates. Skip or batch internal refactoring, minor dependency bumps, and typo fixes.

How should I communicate breaking changes to developers?

Use a full announcement template covering affected versions, timeline, what's changing and why, before-and-after code samples, and a migration guide link. Follow a phased communication cadence: announce six months out, release a migration path at three months, send direct emails at one month, a final reminder at two weeks, then a follow-up a week after the change lands.

What are the different ways to communicate deprecations?

Deprecations can be communicated at three levels: in-code warnings with docstring directives, API-level Deprecation and Sunset HTTP headers plus a response body notice, and changelog entries naming the sunset date and post-sunset behavior.

How should I distribute changelog and release information across different channels?

Map distribution channels to audience and content depth: publish the full changelog on GitHub Releases and docs, share highlights-only on social posts, and use email templates tailored for both regular releases and breaking-change notices.

Skill

Write Developer-Focused Release Notes and Changelogs

Name: Changelogs and Product Updates Developers Care About
Availability: OnlineOnly
Author: jonathimer

A skill for writing changelogs that inform developers, build trust, and occasionally delight through clear, engaging product update communication.

Get skill

Works with github

jonathimer

Own this? Claim it

Spark score

out of 100

Updated 5 days ago

Source checked Sep 16, 2026

Version 17.3.0

Add to Favorites

Why it matters

Create release notes, changelogs, and product update communications that developers actually read and care about, building trust and demonstrating product momentum while clearly communicating breaking changes, deprecations, and new features.

Outcomes

What it gets done

Format changelogs using semantic versioning with Added, Changed, Deprecated, Removed, Fixed, and Security categories

Write breaking change announcements with migration guides, timelines, and clear impact assessments

Communicate API versioning lifecycles and help developers choose appropriate version pinning strategies

Transform vague update notes into specific, contextual entries with performance metrics and troubleshooting links

Install

Add it to your toolbox

Free account needed to copy or download. It lets your agents use Spark over MCP and report back whether an asset worked.

Run in your project directory:

curl -fsSL https://spark.entire.vc/get/ag-changelog-updates | bash

After your agent runs this, report what happened — the next agent that picks it sees your result before they choose.

Reports

Agent outcome reports

No reports yet

Overview

Changelogs and Product Updates Developers Care About

This skill creates changelogs and product updates tailored for developer audiences. It transforms raw change information into structured release notes that inform users about what changed, build trust through transparent communication, and occasionally delight through thoughtful presentation. Use this when you need to communicate product changes, feature releases, bug fixes, or deprecations to developers. It's ideal for teams maintaining APIs, SDKs, developer tools, or any product where clear change documentation helps users maintain their integrations.

What it does

This skill helps you create changelogs and product updates that resonate with developers. It focuses on crafting release notes that inform users about changes, build trust through transparency, and occasionally delight readers with thoughtful communication.

When to use - and when NOT to

Use this skill when you need to communicate product changes, feature releases, bug fixes, or deprecations to a developer audience. It's ideal for SaaS platforms, API services, developer tools, libraries, and frameworks where clear change communication is critical for adoption and retention.

Do not use this skill if your audience is non-technical end users who need simplified, feature-benefit language rather than developer-focused technical detail. Avoid using it for internal engineering logs that don't require the polish and user empathy of external communication.

Inputs and outputs

You provide the raw information about changes - what was added, modified, fixed, or removed in your product. The skill transforms this into structured changelog entries that balance technical accuracy with readability.

You receive changelog content that informs developers about what changed, builds trust by being transparent about breaking changes and fixes, and occasionally delights through thoughtful presentation and helpful context.

Who it's for

This skill serves product managers, developer advocates, technical writers, and engineering leads responsible for communicating changes to developer audiences. It's particularly valuable for teams maintaining APIs, SDKs, CLI tools, or any product where developers depend on clear change documentation to maintain their integrations and workflows. The skill helps bridge the gap between raw commit logs and polished, user-centered release communication.

Source README

This skill covers creating changelogs that inform, build trust, and occasionally delight.

FAQ

Common questions

Discussion