API deprecation strategy

Severity: Optional

If multiple API versions exist, there should be a plan for sunsetting old versions.

Check automatically:

1. Check for deprecation headers in code:

# RFC 8594 Deprecation header
grep -rE "Deprecation|Sunset|deprecat" src/ app/ lib/ --include="*.ts" --include="*.js" --include="*.py" 2>/dev/null

# Custom deprecation warnings
grep -rE "deprecated|will be removed|end of life|sunset" src/ app/ lib/ 2>/dev/null | grep -i api

2. Check documentation for deprecation policy:

# Deprecation in docs
grep -riE "deprecat|sunset|migration|upgrade" docs/ README.md CHANGELOG.md API.md 2>/dev/null

# Version lifecycle documentation
grep -riE "version.*lifecycle|api.*lifecycle|supported.*version" docs/ README.md 2>/dev/null

3. Check for deprecated route markers:

# JSDoc/annotations
grep -rE "@deprecated|#.*deprecated|//.*deprecated" src/ app/ routes/ 2>/dev/null

# Deprecation logging
grep -rE "console\.(warn|log).*deprecat|log.*deprecat|warning.*deprecat" src/ app/ 2>/dev/null

4. Check for migration guides:

# Migration documentation
ls -la docs/*migration* docs/*upgrade* MIGRATION* UPGRADE* 2>/dev/null

# Version-specific docs
ls -la docs/v1* docs/v2* 2>/dev/null

Ask user:

• "How many API versions are currently active?"
• "What's the timeline for deprecating old versions?"
• "Is there a migration guide for consumers?"

Cross-reference with:

• API-001 (versioning strategy)
• DOC-001 (documentation should cover deprecation)

Pass criteria:

• Deprecation strategy documented OR implemented (headers/warnings), OR
• Single version exists (no deprecation needed yet)
• Migration guides available for version upgrades

Fail criteria:

• Multiple versions exist with no deprecation plan
• Old versions still active with no sunset timeline
• No migration path documented between versions
• Deprecated endpoints without warnings to consumers

Evidence to capture:

• Number of active versions
• Deprecation mechanisms in use (headers, warnings, docs)
• Migration documentation availability
• Sunset timeline if defined

---