Skip to main content

Migration Plan

:::info Source Sourced from services/progress-service/MIGRATION_PLAN.md in the documentation repo. :::

1. Core Rules​

  • xAPI 1.0.3 schema frozen (external spec). Platform extensions under http://ghasi.io/xapi/....
  • Attempt lifecycle frozen at M1; new states require major version + migration.
  • Statements append-only; never altered except via GDPR erasure.
  • Partitioning scheme stable; migration via detach + re-attach.

2. Schema Evolution​

  • Add columns to attempts, completion_records: additive.
  • New verbs: register in verb vocabulary; additive.
  • New extensions in context.extensions: additive.
  • Statement schema changes require xAPI spec compatibility.

3. API Evolution​

  • xAPI /xapi/* follows xAPI spec; no custom versioning.
  • Internal /api/v1/* follows platform rules (major bump for breaking).

4. Event Evolution​

EventVersionPolicy
progress.statement.stored.v1v1Additive only
progress.attempt.closed.v1v1Outcome enum additive
progress.completion.recorded.v1v1Evidence field additive
progress.score.recorded.v1v1Additive

5. xAPI Version Migration​

  • xAPI 1.0.3 → 2.0 (future): will be a major v2 endpoint path. Dual-serve during migration.
  • 3rd-party LRSes declare supported version; server negotiates on About endpoint.

6. Partition Migration​

  • Partition detach schedule documented.
  • Old partitions archived to S3 Parquet; reattachable as foreign tables for historical queries.
  • Partition scheme change (e.g., weekly instead of monthly) requires offline migration; rare.

7. Retention Policy Migration​

  • Tenant-level retention overrides handled via policy table.
  • Changes trigger a re-evaluation of archived partitions.
  • Regulated class (7-year cold) cannot be shortened without compliance sign-off.

8. Data Residency​

  • Participate in Data Residency Migration Saga.
  • Steps:
    • Freeze ingest at source for tenant.
    • Bulk export statements + attempts + completions.
    • Rebuild projections + partitions in target.
    • Verify checksum of statement counts per (month, verb).
    • Unfreeze.

9. GDPR Erasure Migration​

  • Erasure saga participation documented; replay test ensures:
    • Statements deleted.
    • Anonymized aggregates retained where legal.
    • Audit trail of erasure logged (immutable).

10. Tenant Migration Runbook​

Per ../tenant-service/MIGRATION_PLAN.md §10.

11. Changelog​

Per-release: schema changes, new verbs, new extension namespaces, xAPI conformance version.