Backward Compatibility Rules
Comprehensive guide to backward compatibility rules for APIs, databases, and data contracts with migration strategies and testing approaches
npx skills add majiayu000/claude-skill-registry --skill backward-compat-rules --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
What it does
Provides a structured guide on backward compatibility across APIs, databases, and data contracts, including definitions, example scenarios, compatibility levels, safe and breaking changes, migration steps, testing approaches, and deprecation strategies.
How it works
Outlines concrete concepts and step-by-step examples for:
- Definition of backward compatibility and evolution design
- Compatibility levels (Backward, Forward, Full, Breaking)
- REST API, Database, Event/Message, GraphQL compatibility rules with examples of safe and breaking changes
- Deprecation strategies and migration guidance (sunset dates, notices, migration guides)
- Multi-step migrations and API versioning strategies
- Testing approaches (contract tests, integration tests with old clients, schema checks, canary deployments)
- Tools and commands for compatibility checks (OpenAPI, GraphQL, Protobuf, JSON Schema) including example commands
- How to communicate breaking changes (changelog, migration guides, deprecation signals)
When to use it
Use when planning or validating backward compatibility policies for APIs, databases, and data contracts; apply during version upgrades, migrations, or deprecation projects to ensure old clients continue functioning or migrate gradually.
What it can touch
Tools referenced include: OpenAPI tools (oasdiff, openapi-diff), GraphQL tooling (graphql-inspector), Protobuf tooling (buf), JSON Schema validators, and general testing code samples shown in JavaScript/JSON snippets. Specific commands and code blocks are provided to perform diffs, checks, and migrations.
Caveats
Contains examples and guidance only; relies on stated procedures and does not guarantee successful migrations without client coordination. No licensing changes beyond MIT as stated in repository metadata.
# Backward Compatibility Rules ## What is Backward Compatibility? **Definition:** New version works with old clients without requiring changes. ### Example ``` API v1: GET /users → { id, name } API v2: GET /users → { id, name, email } (added field) Old client (expects v1) calls v2 API: → Receives { id, name, email } → Ignores 'email' field → Works! ✅ Backward compatible ``` ### Evolution Design ``` Version 1.0 → 1.1 → 1.2 → 2.0 ↓ ↓ ↓ ↓ Compatible Compatible Breaking ``` --- ## Why Backward Compatibility Matters ### 1. Avoid Breaking Existing Integrations **Without Backward Compatibility:** ``` Deploy new API version → All clients break immediately → Emergency rollback → Coordinate with all clients to update → Big bang migration (risky!) ``` **With Backward Compatibility:** ``` Deploy new API version → Old clients continue working → Clients migrate gradually → No coordination needed ``` ### 2. Gradual Migration (Not Big Bang) **Timeline:** ``` Month 0: Deploy v2 (backward compatible) Month 1: 20% of clients migrated Month 3: 50% of clients migrated Month 6: 80% of clients migrated Month 12: 100% migrated, deprecate v1 ``` ### 3. Reduce Coordination Overhead **Without:** - Coordinate
- What is Backward Compatibility?
- Example
- Evolution Design
- Why Backward Compatibility Matters
- 1. Avoid Breaking Existing Integrations
- 2. Gradual Migration (Not Big Bang)
- 3. Reduce Coordination Overhead
- 4. Customer Trust (Stable APIs)
- Compatibility Levels
- Backward Compatible (New Server, Old Client)
- Forward Compatible (Old Server, New Client)
- Full Compatible (Both Directions)
- Breaking Change (Incompatible)
- REST API Backward Compatibility
oasdiff breaking old.yaml new.yaml npm install -g @graphql-inspector/cli graphql-inspector diff old.graphql new.graphql brew install bufbuild/buf/buf buf breaking --against .git#branch=main Migration tool Scans code for v1 API calls Suggests v2 equivalents Optionally auto-updates code
What does the Backward Compatibility Rules skill do?
Comprehensive guide to backward compatibility rules for APIs, databases, and data contracts with migration strategies and testing approaches
How do I install it?
Run `npx skills add majiayu000/claude-skill-registry --skill backward-compat-rules --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From majiayu000/claude-skill-registry, a repository with 534 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.