gitscape.ai: Skill for Claude Code

Deprecation and Migration

Overview

Code is a liability, not an asset. Every line maintained is a line that can break. Deprecation is the practice of systematically retiring code, APIs, or features that are no longer earning their maintenance cost. Do it deliberately, not by abandonment.

When to Use

• Removing an old API endpoint that has been replaced
• Migrating from one library or pattern to another
• Sunsetting a feature that is no longer used or supported
• Cleaning up dead code identified during a refactor

The Deprecation Mindset

Compulsory vs. Advisory Deprecation:

Type	Meaning	Example
Compulsory	Will be removed on a specific date — users must migrate	Old /v1/skills endpoint being replaced by /v2/skills
Advisory	Discouraged but not being removed yet	A config option that has a better alternative

Always be explicit about which type you are doing.

The Deprecation Process

Step 1: Document Before Removing

Before removing anything, document:

• What is being deprecated
• Why (the reason, not just "it's old")
• What the replacement is
• When removal will happen (for compulsory deprecation)

# api/app/routes/skills_v1.py

import warnings

@router.get("/v1/skills/{repo}")
async def get_skill_v1(repo: str):
    """
    DEPRECATED: Use /v2/skills/{repo} instead.
    This endpoint will be removed on 2026-09-01.
    Migration guide: docs/migration/v1-to-v2.md
    """
    warnings.warn(
        "GET /v1/skills is deprecated. Use /v2/skills. Removal: 2026-09-01.",
        DeprecationWarning,
        stacklevel=2,
    )
    # Delegate to v2 during transition period
    return await get_skill_v2(repo)

Step 2: Add Deprecation Signals

Make deprecation visible to consumers:

For HTTP APIs:

# Add Deprecation and Sunset headers per RFC 8594
response.headers["Deprecation"] = "true"
response.headers["Sunset"] = "Tue, 01 Sep 2026 00:00:00 GMT"
response.headers["Link"] = '</v2/skills>; rel="successor-version"'