Skip to content

feat(core): add upgrade and migration system #11

@CalvinAllen

Description

@CalvinAllen

Critical infrastructure for handling dtvem upgrades and breaking changes in directory structure.

Phase 1: Installation Version Tracking

  • Create ~/.dtvem/config/metadata.json to track installation version
  • Add structure_version field (increment when directory structure changes)
  • Add installation_version field (tracks dtvem version that created the installation)
  • Add last_upgraded timestamp field

Phase 2: Migration Framework

  • Create internal/migration/ package with migration system
  • Define Migration type with FromVersion, ToVersion, Migrate(), Rollback()
  • Implement migration runner that chains migrations (1 → 2 → 3)
  • Add automatic migration check on command startup (CheckAndMigrate())
  • Backup old structure before migrating (safety net)
  • Make migrations idempotent (safe to run multiple times)

Phase 3: Migration Types

  • Auto-migrate (safe changes): Adding directories, adding config fields, renaming files
  • Prompted migrations (risky changes): Deleting directories, config format changes, major restructuring
  • Show migration plan before applying (list of migrations, from/to versions)
  • Allow user confirmation or decline
  • Provide manual migration command: dtvem migrate-installation

Phase 4: Install Script Upgrade Handling

  • Detect existing dtvem installation in install.sh and install.ps1
  • Read currently installed version (dtvem version)
  • Compare with version to be installed
  • Skip if same version already installed
  • Backup old binary before replacing (.backup suffix with timestamp)
  • Replace binary if newer version
  • Warn if trying to downgrade
  • Run post-upgrade migrations automatically

Phase 5: Self-Upgrade Command

  • Create dtvem upgrade or dtvem self-update command
  • Check GitHub releases API for latest version
  • Compare with current version (version.Version)
  • Show what's new (changelog from GitHub release)
  • Download new binary to temp location
  • Handle cross-platform binary replacement:
    • Unix: Can replace running binary (OS holds old one in memory)
    • Windows: Cannot replace running .exe (file locking issue)
      • Download as dtvem-new.exe
      • Spawn with --finalize-upgrade flag
      • Exit current process
      • New binary replaces old one
  • Verify new installation (dtvem version check)
  • Clean up temp files
  • Support --check flag (check for updates without installing)
  • Support version pinning: dtvem upgrade --version 1.2.0

Testing & Safety

  • Test migrations on VMs with old versions
  • Test rollback procedures
  • Document manual recovery steps
  • CI tests for migration paths
  • Never break existing installations silently

Example Scenarios to Handle:

  • Config file format changes (runtimes.json → nested structure)
  • Directory reorganization (config/ → split into config/ + cache/)
  • Shim architecture changes (new shim template format)
  • PATH configuration changes (different directories in PATH)

Implementation Files:

  • internal/migration/migration.go - Migration framework
  • internal/migration/migrations.go - Concrete migration definitions
  • internal/config/metadata.go - Installation metadata handling
  • src/cmd/upgrade.go - Self-upgrade command
  • install.sh and install.ps1 - Version detection and upgrade logic

Priority: High - Essential for maintaining stable releases and user trust

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions