# Changelog Design > Use when preparing release changelogs, migration guides, or breaking change communication for consumers. Covers change categorization, before/after documentation, migration step authoring, semver version strategy, and release communication planning. Do not use for documentation architecture planning (use documentation-plan) or recording architectural decisions (use adr-template). - Skill: `tomevault-io/changelog-design` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/changelog-design` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/changelog-design/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/changelog-design --- # Changelog Design ## Purpose Create structured changelog entries and migration guides that enable consumers to understand changes, assess impact, and upgrade safely. Produces versioned changelogs following Keep a Changelog format with step-by-step migration instructions for breaking changes. ## Scope Constraints Reads commit history, PR descriptions, and existing changelog entries to produce release documentation. Does not modify source code, bump version numbers, or publish releases. ## Inputs - List of changes (commits, PRs, or feature descriptions) - Current version number - Consumer types (library users, API consumers, internal teams) - Previous changelog entries (for format consistency) ## Input Sanitization No user-provided values are used in commands or file paths. All inputs are treated as read-only analysis targets. ## Procedure ### Progress Checklist - [ ] Step 1: Categorize all changes - [ ] Step 2: Describe each change with full context - [ ] Step 3: Write migration steps for breaking changes - [ ] Step 4: Define version strategy - [ ] Step 5: Plan communication - [ ] Step 6: Validate migration path ### Step 1: Categorize All Changes Classify each change by impact: - **Breaking**: Requires consumer action to upgrade — API changes, removed features, changed behavior - **Feature**: New capability with no impact on existing behavior — additive APIs, new options - **Fix**: Bug resolution — corrected behavior, error handling improvements - **Deprecation**: Future removal warning — still works but will be removed in a future version - **Internal**: No consumer impact — refactoring, dependency updates, test improvements - Flag any change where the category is ambiguous and err toward higher impact classification ### Step 2: Describe Each Change with Full Context Write each changelog entry with: - **What changed**: Precise description of the change (not the PR title — the user-facing impact) - **Why**: Motivation for the change — what problem it solves or what improvement it brings - **Who is affected**: Which consumers or use cases are impacted - **Before/After**: For behavior changes, show what the old behavior was and what the new behavior is - Link to relevant PR, issue, or discussion for additional context ### Step 3: Write Migration Steps for Breaking Changes For each breaking change, provide a complete migration guide: - **Step-by-step instructions**: Numbered steps from old code to new code - **Before/after code examples**: Show the exact code change needed (not just description) - **Automated migration**: Codemod or find-and-replace pattern if applicable - **Partial migration support**: Can consumers upgrade incrementally, or is it all-or-nothing? - **Testing the migration**: How to verify the upgrade was successful - **Estimated effort**: Time estimate for migrating (minutes, hours, or days) ### Step 4: Define Version Strategy Determine version bump based on changes: - **Major (X.0.0)**: Breaking changes present — any consumer code may need modification - **Minor (0.X.0)**: New features, no breaking changes — upgrade is safe, new capabilities available - **Patch (0.0.X)**: Bug fixes only — upgrade is safe, existing behavior corrected - If multiple change categories exist, the highest impact category determines the version bump - Consider pre-release versions (alpha, beta, rc) for high-risk changes needing early feedback ### Step 5: Plan Communication Design the release communication: - **Changelog entry**: Formatted entry for CHANGELOG.md (Keep a Changelog format) - **Migration guide**: Standalone document for breaking changes (linked from changelog) - **Upgrade notification**: How consumers are informed — release notes, email, in-app notification - **Deprecation timeline**: For deprecated features, when will they be removed? (Minimum 1 major version) - **Support period**: How long will the previous version receive bug fixes? ### Step 6: Validate Migration Path Verify the upgrade experience: - **Incremental upgrade**: Can consumers upgrade from any previous version, or only from N-1? - **Breaking change clusters**: Are multiple breaking changes better released together or separately? - **Dependency conflicts**: Does this upgrade force consumers to update other dependencies? - **Rollback safety**: Can consumers downgrade if the upgrade causes issues? - **CI verification**: Run consumer-perspective tests against the new version to catch missed breaking changes > **Compaction resilience**: If context was lost during a long session, re-read the Inputs section to reconstruct what system is being analyzed, check the Progress Checklist for completed steps, then resume from the earliest incomplete step. ## Output Format ```markdown # Changelog: v[X.Y.Z] **Release date**: [YYYY-MM-DD] **Version bump**: [Major | Minor | Patch] — [one-line reason] ## Breaking Changes ### [Change title] [Description of what changed and why] **Who is affected**: [which consumers/use cases] **Before**: ```[language] // old code ``` **After**: ```[language] // new code ``` **Migration steps**: 1. [Step 1] 2. [Step 2] 3. [Verify by running ...] --- ## Features - **[Feature name]**: [Description] ([#PR](link)) ## Fixes - **[Fix description]**: [What was wrong, what's corrected] ([#PR](link)) ## Deprecations - **[Deprecated item]**: Use [replacement] instead. Will be removed in v[X+1].0.0. ([#PR](link)) --- ## Migration Guide ### Prerequisites - [Required version of dependencies] - [Backup/snapshot recommendation] ### Step-by-Step Upgrade 1. Update dependency: `[package manager command]` 2. [Breaking change 1 migration steps with code] 3. [Breaking change 2 migration steps with code] 4. Run tests: `[test command]` 5. Verify: [smoke test or manual check] ### Estimated Migration Effort - **Small projects**: [time estimate] - **Large projects**: [time estimate] ## Communication Plan | Channel | Content | Timing | |---------|---------|--------| | CHANGELOG.md | Full changelog | On release | | GitHub Release | Highlights + migration link | On release | | [notification channel] | Breaking change summary | 1 week before release | ``` ## Handoff - Hand off to adr-template if the changelog reveals significant architectural decisions that lack formal ADR documentation. - Hand off to documentation-plan if the release introduces new features or APIs that require documentation strategy updates. ## Quality Checks - [ ] Every change is categorized (breaking, feature, fix, deprecation, internal) - [ ] Breaking changes have before/after code examples - [ ] Migration guide provides step-by-step instructions with verification - [ ] Version bump follows semver correctly based on change categories - [ ] Deprecations include replacement guidance and removal timeline - [ ] Communication plan covers all consumer notification channels - [ ] Migration path is validated — consumers can upgrade incrementally - [ ] Changelog follows Keep a Changelog format consistently ## Evolution Notes --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/dtsong) — claim your Tome and manage your conversions.