api-changelog-versioning
Scannednpx machina-cli add skill secondsky/claude-skills/api-changelog-versioning --openclawFiles (1)
SKILL.md
1.9 KB
API Changelog & Versioning
Document API changes with clear migration paths and deprecation timelines.
Changelog Structure
# 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
## Migrating from v2 to v3
### Before (v2)
```json
{ "user_name": "john" }
After (v3)
{ "data": { "type": "user", "attributes": { "name": "john" } } }
Steps
- Update SDK to v3.x
- Modify response handlers
- Test in staging environment
- 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
Source
git clone https://github.com/secondsky/claude-skills/blob/main/plugins/api-changelog-versioning/skills/api-changelog-versioning/SKILL.mdView on GitHub Overview
api-changelog-versioning helps you document API changes with clear migration paths and deprecation timelines for API consumers. It guides you through structuring changelogs, crafting migration steps, and communicating versioned changes to developers.
How This Skill Works
The skill follows a standardized Changelog Structure with version blocks, including sections for Breaking Changes and Migration Steps, plus a Deprecation Schedule. It also provides a Migration Guide Template to map Before/After payloads and a Version Support Policy, enabling consistent, actionable upgrade guidance for API clients.
When to Use It
- When managing API versions and introducing breaking changes.
- When communicating deprecations with clear timelines.
- When creating upgrade guides for developers.
- When documenting new features within a versioned changelog.
- When aligning SDKs and client docs with URL-based versioning.
Quick Start
- Step 1: Create a versioned changelog document with sections for Breaking Changes, Migration Steps, and Deprecation Schedule.
- Step 2: Add a Migration Guide Template showing Before and After payloads and concrete steps to upgrade.
- Step 3: Publish the document and communicate versioned changes to consumers, using URL-based versioning for clarity.
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.
Example Use Cases
- Changelog for v3.0.0 with Breaking Changes: JSON:API format and JWT Bearer authentication.
- v2.5.0 highlights: Webhook support, batch operations, field filtering.
- Deprecation Schedule table showing versions and ongoing support.
- Migration Guide Template illustrating Migrating from v2 to v3 with Before/After payloads.
- Best Practices section demonstrating deprecation notices and URL-versioning.
Frequently Asked Questions
Add this skill to your agents
