Release Collector: Design version-level deprecation/obsolescence tracking

[hdamker]

Issue: Design version-level deprecation/obsolescence tracking

Description

The Release Collector V3 system currently has no mechanism to mark specific API versions as deprecated or obsolete. This is needed to help API consumers understand which versions are still supported and which should be migrated away from.

Important: This is about tracking version-level lifecycle (e.g., "quality-on-demand v1.0 is deprecated, use v2.0"), not deprecating entire APIs.

Problem

Currently, there is no way to:

• Distinguish between active and deprecated API versions in viewers
• Track version lifecycle states (active → deprecated → obsolete)
• Communicate sunset/removal dates for old versions
• Guide users to replacement versions
• Provide deprecation rationale and migration notes

Design Challenge

The existing api-landscape.yaml configuration file only tracks API-level metadata (categories, URLs, descriptions) with no notion of versions or releases. The deprecation/obsolescence information needs to be version-specific.

Required Design Discussion

This issue should START with design proposals addressing:

1. Where to store version-level metadata?

Options to consider:

• Option A: Extend api-landscape.yaml to include version-specific sections
• Option B: Create new file (e.g., api-version-lifecycle.yaml)
• Option C: Add to releases-master.yaml during analysis phase
• Option D: Separate enrichment source with its own schema

2. What information to track per version?

Potential fields:

• status: active | deprecated | obsolete | sunset
• deprecated_since: Meta-release or date when deprecated
• sunset_date: When the version will be removed/unsupported
• replacement: Version to migrate to
• deprecation_reason: Brief explanation
• migration_guide_url: Link to migration documentation

3. How to apply in viewers?

• Display deprecation badges/indicators
• Add filtering options ("hide deprecated versions", "show only active")
• Show warning messages for deprecated versions
• Link to migration guides
• Sort/group deprecated versions separately

Example Design (Option B)

# New file: api-version-lifecycle.yaml
metadata:
  version: 1.0.0
  description: Version-level lifecycle tracking for CAMARA APIs

api_versions:
  quality-on-demand:
    "1.0":
      status: deprecated
      deprecated_since: Fall25
      sunset_date: 2026-12-31
      replacement: "2.0"
      notes: "Superseded by v2.0 with improved QoS profiles"
    "1.1":
      status: deprecated
      deprecated_since: Spring25
      replacement: "2.0"
    "2.0":
      status: active

  sim-swap:
    "1.0":
      status: active

Implementation Phases

1. Phase 1: Design (this issue)

   • Community discussion on storage approach
   • Define schema for version lifecycle metadata
   • Document deprecation process

2. Phase 2: Implementation (future issue)

   • Implement chosen design
   • Update enrichment logic
   • Modify viewer templates and filtering
   • Add schema validation

3. Phase 3: Documentation (future issue)

   • Document deprecation workflow
   • Create maintainer guide
   • Update API lifecycle documentation

Affected Areas (After Design)

• Schema/configuration files
• Enrichment logic (scripts/lib/enrichment.js)
• Viewer library (templates/viewer-lib.js) - filtering/rendering
• Viewer templates (all .html templates) - display badges
• Documentation - lifecycle management process

Context

Identified in PR review: #68 (comment)

Quote from review: "no formal 'deprecated' status exists yet but agreed such a field should be anticipated in api-landscape.yaml configuration for future implementation"

Priority

Low - Future planning, no immediate need. This is a forward-looking enhancement to improve API lifecycle communication.

Labels

enhancement, design-needed, low-priority, lifecycle-management