mcpField
A
api-changelog-versioning

api-changelog-versioning

github.com/aj-geddesDevelopment373474 installsUpdated 34w ago
Repository

About api-changelog-versioning

A skill for documenting API releases, including changes, deprecations, breaking changes, and migration guidance. It supports version comparisons and semantic versioning practices.

Key features

  1. 01Document API changes by version
  2. 02Mark breaking changes clearly
  3. 03Write migration guides with examples
  4. 04Record deprecations and support policies
  5. 05Apply semantic versioning practices

Use cases

  1. 01Preparing a release changelog
  2. 02Explaining a breaking API update
  3. 03Guiding consumers through an upgrade
  4. 04Recording deprecation timelines

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/aj-geddes/useful-ai-prompts --skill api-changelog-versioning

After installing, type/api-changelog-versioningin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/
breaking-changes.md
improvements.md
new-features.md
security.md
step-1-update-base-url.md
scripts/
validate-api.sh
templates/
api-scaffold.yaml

Details

From the project README

API Changelog & Versioning

Table of Contents

Overview

Create comprehensive API changelogs that document changes, deprecations, breaking changes, and provide migration guides for API consumers.

When to Use

  • API version changelogs
  • Breaking changes documentation
  • Migration guides between versions
  • Deprecation notices
  • API upgrade guides
  • Backward compatibility notes
  • Version comparison

Quick Start

  • Version comparison
# API Changelog

## Version 3.0.0 - 2025-01-15

### 🚨 Breaking Changes

#### Authentication Method Changed

**Previous (v2):**

```http
GET /api/users
Authorization: Token abc123
```

## Reference Guides

Detailed implementations in the `references/` directory:

| Guide | Contents |
|---|---|
| [🚨 Breaking Changes](references/breaking-changes.md) | 🚨 Breaking Changes |
| [✨ New Features](references/new-features.md) | ✨ New Features |
| [🔧 Improvements](references/improvements.md) | 🔧 Improvements |
| [🔒 Security](references/security.md) | 🔒 Security, 🗑️ Deprecated, 📊 Version Support Policy |
| [Step 1: Update Base URL](references/step-1-update-base-url.md) | Step 1: Update Base URL, Step 2: Migrate Authentication, Step 3: Update Response Parsing, Step 4: Update Error Handling (+2 more) |

## Best Practices

### ✅ DO

- Clearly mark breaking changes
- Provide migration guides with code examples
- Include before/after comparisons
- Document deprecation timelines
- Show impact on existing implementations
- Provide SDKs for major versions
- Use semantic versioning
- Give advance notice (3-6 months)
- Maintain backward compatibility when possible
- Document version support policy

### ❌ DON'T

- Make breaking changes without notice
- Remove endpoints without deprecation period
- Skip migration examples
- Forget to version your API
- Change behavior without documentation
- Rush deprecations

Comments

Markdown supported