version-compatibility

Evaluate API, schema, event, and configuration changes for mixed-version compatibility.

4|Updated May 16, 2026
One-click install
npx skills add https://github.com/machenjie/rd-skills --skill version-compatibility
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: version-compatibility
Source: https://github.com/machenjie/rd-skills/tree/main/src/foundation/capabilities/version-compatibility
Command: npx skills add https://github.com/machenjie/rd-skills --skill version-compatibility

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Prevents breaking behavior when APIs, schemas, events, configuration, and observable behavior evolve while old and new producers/consumers coexist during rollout and rollback scenarios.

Core Features & Use Cases

  • End-to-end compatibility evaluation: Assesses compatibility across contract surfaces including structure, meaning, validation, defaults, and behavior.
  • Bidirectional safety checks: Verifies both “old producer → new consumer” and “new producer → old consumer,” including rollback after mixed deployments.
  • Breaking-change governance: Requires explicit mitigations for breaking changes via versioning, backward-compatible bridge, or expand-contract migration path with rollback safety.
  • Rollout and deprecation discipline: Defines mixed-version behavior, rollout sequencing (expand before contract), and telemetry-gated deprecation/removal criteria.

Use case example: When adding a new request field or changing enum/validation rules for a public endpoint or event, use this capability to determine whether the change is safe, what mitigation is required, and how to sequence deployment to avoid data corruption and consumer failures.

Quick Start

Ask for a compatibility assessment by describing the proposed change, the affected contract surfaces, and the current and target versions, then request a rollout and rollback-safe migration plan.

Frequently Asked Questions about version-compatibility

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I assess API versioning compatibility for staged rollouts?

Schema evolution in event-driven systems is safe when consumers cannot be upgraded atomically by applying expand-contract patterns. You must evaluate forward and backward compatibility across contract surfaces and sequence deployments expand-first to prevent data corruption during mixed-version coexistence.

What is the best way to prevent breaking changes during a canary release?

Yes, rollback safety after mixed deployments requires verifying that new producers can revert to old schemas without corrupting stored data or breaking old consumers. You must validate bidirectional compatibility and ensure deprecation removal is telemetry-gated to confirm all consumers upgraded.

When do I need contract compatibility checks for configuration changes?

You need contract compatibility checks for configuration changes when defaults, validation rules, or observable behavior evolve while old and new producers coexist. Evaluate these changes across structure, meaning, and defaults to prevent behavior mismatches during staged rollouts and deprecations.

How do I sequence expand-contract migrations to avoid consumer failures?

Sequence expand-contract migrations by deploying backward-compatible expansion phases first, allowing all consumers to upgrade safely before contracting or removing old fields. Use telemetry gating to verify consumer upgrades before finalizing deprecation removal and contract evolution.