playbooks

home / skills / secondsky / claude-skills / api-changelog-versioning

api-changelog-versioning skill

/plugins/api-changelog-versioning/skills/api-changelog-versioning

This skill generates comprehensive API changelogs and migration guides, clarifying breaking changes, deprecations, and upgrade steps for API consumers.

npx playbooks add skill secondsky/claude-skills --skill api-changelog-versioning

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
1.9 KB
---
name: api-changelog-versioning
description: Creates comprehensive API changelogs documenting breaking changes, deprecations, and migration strategies for API consumers. Use when managing API versions, communicating breaking changes, or creating upgrade guides.
---

# API Changelog & Versioning

Document API changes with clear migration paths and deprecation timelines.

## Changelog Structure

```markdown
# API Changelog

## v3.0.0 (2025-01-15) - Breaking Changes

### Breaking Changes
- Response format now follows JSON:API specification
- Authentication switched from API tokens to JWT Bearer

### Migration Steps
1. Update base URL to `/api/v3`
2. Replace `Authorization: Token xxx` with `Authorization: Bearer xxx`
3. Update response parsing for new envelope format

## v2.5.0 (2024-12-01) - Features

### New Features
- Webhook support for order events
- Batch operations endpoint
- Field filtering via `?fields=` parameter

### Improvements
- 56% faster response times on /products
- Enhanced error messages with field-specific suggestions
```

## Deprecation Schedule

| Version | Status | Support Until |
|---------|--------|---------------|
| v3.x | Current | Full support |
| v2.x | Maintenance | 2025-06-01 |
| v1.x | EOL | Unsupported |

## Version Support Policy

- **Current**: Full support, new features
- **Maintenance**: Bug fixes and security only
- **EOL**: No support, remove from docs

## Migration Guide Template

```markdown
## Migrating from v2 to v3

### Before (v2)
```json
{ "user_name": "john" }
```

### After (v3)
```json
{ "data": { "type": "user", "attributes": { "name": "john" } } }
```

### Steps
1. Update SDK to v3.x
2. Modify response handlers
3. Test in staging environment
4. Update production
```

## Best Practices

- Provide 3-6 months deprecation notice
- Include before/after code examples
- Mark breaking changes prominently
- Maintain backward compatibility when feasible
- Version via URL path (`/api/v1/`) for clarity

Overview

This skill creates comprehensive API changelogs and versioning guidance to document breaking changes, deprecations, and migration strategies for API consumers. It produces clear changelog entries, deprecation schedules, and migration guides with before/after examples. The output is structured for publication in docs or release notes and tailored to maintainers and integrators.

How this skill works

The skill analyzes proposed or implemented API changes and generates a structured changelog with sections for breaking changes, features, improvements, and migration steps. It also produces a deprecation schedule and a version support policy, plus concrete code snippets showing before/after payloads and step‑by‑step migration actions. Outputs are formatted for easy inclusion in documentation or release notes.

When to use it

  • Preparing release notes for a new API version with breaking changes
  • Communicating deprecation timelines and support windows to integrators
  • Creating migration guides and code examples for SDK or client updates
  • Establishing or updating a version support policy for your API
  • Documenting incremental features, improvements, and performance fixes

Best practices

  • Mark breaking changes clearly at the top of each release entry
  • Provide 3–6 months deprecation notice and a clear support-until date
  • Include before/after code examples for common client workflows
  • Recommend a versioning strategy (URL path versioning like /api/v1/) for clarity
  • List concrete migration steps and update SDK upgrade instructions
  • Prefer backward compatibility where feasible and document tradeoffs

Example use cases

  • Generate a v3.0.0 release note that lists breaking auth changes and response envelope migration steps
  • Produce a deprecation schedule table showing Current, Maintenance, and EOL ranges
  • Create a migration guide from v2 to v3 with JSON before/after examples and stepwise testing checklist
  • Draft upgrade instructions for SDK maintainers including code snippets and required config changes
  • Summarize performance improvements and new feature endpoints in a single changelog entry

FAQ

How long should a deprecation notice be?

Provide at least 3–6 months notice, include a clear support-until date, and offer migration guidance and tooling where possible.

What versioning scheme is recommended?

Use semantic versioning and expose the version in the URL path (e.g., /api/v1/) for clarity and predictable routing.