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.

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)

Process

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

Output Format

# 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:

// new code

Migration steps:

1. •[Step 1]
2. •[Step 2]
3. •[Verify by running ...]

Features

• •[Feature name]: [Description] (#PR)

Fixes

• •[Fix description]: [What was wrong, what's corrected] (#PR)

Deprecations

• •[Deprecated item]: Use [replacement] instead. Will be removed in v[X+1].0.0. (#PR)

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

## 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
<!-- Observations appended after each use -->