thefixer3x/version-manager

Skill: Version Manager Guardian

Purpose & Scope

This skill applies when modifying the Version Manager (core/versioning/version-manager.js).

The Version Manager provides:

• Semantic versioning enforcement
• Version compatibility analysis
• Migration handler registration and execution
• Version deprecation management
• Breaking change detection
• Compatibility matrix tracking

Critical Rules - NEVER Do

Version Lifecycle

• NEVER delete versions without deprecation period (minimum 30 days)
• NEVER skip the deprecation phase for any version
• NEVER remove versions that are still in active use
• NEVER change version registration timestamps retroactively

Semver Compliance

• NEVER mark breaking changes as compatible
• NEVER skip major version bump for breaking changes
• NEVER allow non-semver version formats
• NEVER bypass semver validation

Breaking Changes Classification

• NEVER allow these changes in minor/patch versions:
  • Removing endpoints
  • Changing HTTP method (method_changed)
  • Changing path (path_changed)
  • Changing base URL (baseUrl_changed)
  • Adding required parameters
  • Changing parameter types
  • Modifying authentication requirements
  • Changing response structure

Migration Safety

• NEVER skip version compatibility analysis
• NEVER allow migrations without registered handlers
• NEVER execute migrations without rollback capability
• NEVER bypass migration validation

Compatibility Matrix

• NEVER delete compatibility matrix entries
• NEVER falsify compatibility status
• NEVER hide breaking changes in compatibility reports

Required Patterns - MUST Follow

Semver Validation

// MUST validate version format before registration
registerVersion(serviceId, version, config) {
    if (!semver.valid(version)) {
        throw new Error(`Invalid version format: ${version}`);
    }
    // Continue with registration
}

Breaking Change Detection

// MUST detect these as breaking changes:
const breakingChangeTypes = [
    'endpoint_removed',
    'method_changed',
    'path_changed',
    'required_parameter_added',
    'required_parameter_removed',
    'parameter_type_changed',
    'auth_type_changed',
    'baseUrl_changed'
];

// Compatibility MUST be false if any breaking changes exist
compatibility.compatible = compatibility.breakingChanges.length === 0;

Version Registration

// MUST include metadata on registration
this.supportedVersions.set(key, {
    ...config,
    registeredAt: new Date(),
    deprecated: false
});

// MUST create compatibility mappings
this.createCompatibilityMappings(serviceId, version, config);

// MUST emit registration event
this.emit('version:registered', { serviceId, version, config });

Deprecation Process

// MUST follow deprecation protocol
deprecateVersion(serviceId, version, reason) {
    config.deprecated = true;
    config.deprecationReason = reason;
    config.deprecatedAt = new Date();

    this.emit('version:deprecated', { serviceId, version, reason });
}

Migration Handler Registration

// MUST register handlers for version transitions
registerMigrationHandler(serviceId, fromVersion, toVersion, handler) {
    const key = `${serviceId}:${fromVersion}->${toVersion}`;
    this.migrationHandlers.set(key, handler);
}

Event Emission

// MUST emit events for version lifecycle
this.emit('version:registered', { serviceId, version, config });
this.emit('version:deprecated', { serviceId, version, reason });
this.emit('migration:completed', { serviceId, fromVersion, toVersion, data });
this.emit('migration:failed', { serviceId, fromVersion, toVersion, error });

Version Deprecation Timeline

Day 0:    Mark as deprecated, emit 'version:deprecated' event
Day 1-7:  Log warnings for all requests using deprecated version
Day 8-14: Return deprecation headers in responses
Day 15-29: Increase warning severity
Day 30+:  Safe to remove (after migration verification)

Breaking Change Reference

| Change Type | Severity | Version Bump | Migration Required | |-------------|----------|--------------|-------------------| | Endpoint removed | BREAKING | Major | Yes | | Method changed | BREAKING | Major | Yes | | Path changed | BREAKING | Major | Yes | | Required param added | BREAKING | Major | Yes | | Required param removed | BREAKING | Major | Yes | | Param type changed | BREAKING | Major | Yes | | Auth type changed | BREAKING | Major | Yes | | baseUrl_changed | BREAKING | Major | Yes | | Optional param added | Compatible | Minor | No | | New endpoint added | Compatible | Minor | No | | Bug fix | Compatible | Patch | No |

Version Status Lifecycle

REGISTERED -> ACTIVE -> DEPRECATED -> REMOVED
     ^           |
     +-----------+ (rollback possible before deprecation)

• REGISTERED: Version exists but may not be in use
• ACTIVE: Version is in production use
• DEPRECATED: Marked for removal, deprecation period started
• REMOVED: Version no longer supported (30+ days after deprecation)

Integration Points

| Component | Integration Method | |-----------|-------------------| | Base Client | Version passed in request options | | Metrics Collector | Version label in request metrics | | REST API | /v{version}/ path prefix | | MCP Server | Version header in tool calls | | Vendor Abstraction | Version-specific vendor mappings |