Migration Guide
“Migration” is not one compatibility claim. Record five independent scopes before changing anything:
| Scope | Question | Typical evidence |
|---|---|---|
| Source | Does application code compile against the pinned target API? | compiler, unit tests, generated metadata diff |
| Runtime | Does the target lifecycle/configuration start, become ready, process work, and stop correctly? | integration tests, readiness, graceful-shutdown trace/log |
| Storage | Can the target read/write the exact event, snapshot, Redis/Mongo, and BI layouts? | tag-to-tag contract diff, offline inventory, format test |
| Data | Are counts, versions, request IDs, indexes, replayed state, and read models reconciled? | manifest, checksums, representative/full reconciliation |
| Cutover | Is the approved production revision live and observable, with a rehearsed rollback? | deployment digest/revision, live traffic, alert and rollback evidence |
A green local build can close the source gate. It does not close the other four.
Choose a Migration Path
| Current system | Primary path | Why |
|---|---|---|
| CRUD/transaction scripts/direct table writes, no Wow history | Migrating from Traditional Architecture | Establish commands, aggregates, events, import, and traffic ownership |
| Exact Wow v6 tag | Migrate Wow v6 to v8 | Diff pinned platform/API/storage contracts and perform a hard data cutover where required |
| Wow v8 with custom dispatcher/message-bus/Spring lifecycle ownership | Runtime Orchestration Migration | Move lifecycle source code to the unified WowRuntime; this is not automatically a data migration |
Wow v8.16.x using old query APIs or SnapshotRepository | V9 Query Migration | Migrate Gateway/Backend, filters, masking, SnapshotStore, and Spring bean names |
Do not combine first adoption and a v6→v8 upgrade into one undifferentiated release. Select a bounded context and an exact source/target version for each change window.
Documentation Boundaries
| Page | Owns | Does not own |
|---|---|---|
| Traditional architecture | Domain boundary, historical import, shadow catch-up, read/write cutover | Wow version/platform upgrade assumptions |
| v6→v8 | Pinned Gradle/platform matrix, source breaks, storage formats, data cutover | Redesigning every domain |
| Runtime orchestration | RuntimeComponent, message receiver admission, Spring lifecycle ownership, shutdown | Event/snapshot format conversion unless another section requires it |
| V9 query migration | Query Gateway/Backend, filter/masking, SnapshotStore naming, and the Condition migration window | Deployment or production cutover proof |
| Runtime lifecycle | Stable post-migration semantics | The migration procedure itself |
The release notes describe version changes. The selected tag's source, tests, and build files are the exact contract; main is evidence for the current target only.
Shared Completion Gates
Advance only when the current gate has reproducible evidence:
- Scope: pin bounded context, source tag, target tag, datasets/stores, owners, and exclusions.
- Baseline: make source tests green; inventory events/snapshots/keys/collections/read models; create and restore-test a backup.
- Rehearsal: run the same migration tool and manifest against a production-shaped isolated copy.
- Verification: compile, start, process, replay, reconcile, and gracefully stop the target; verify failure paths.
- Cutover: stop admission, drain old writers, migrate once, start one target instance, then move a controlled traffic slice.
- Observation: verify metrics/traces, backend versions, projection/BI lag, alerts, and business invariants.
- Closure: remove old writers/data/bridges only after the rollback window ends.
Rollback must say what happens before and after the first target-version production write. Restoring only the old binary after a new storage-format write is not a rollback.
Legacy Link Navigation
The former single-page topics now live in the three focused guides. These headings and explicit aliases preserve old deep links.
Version Upgrade Guide
See v6 → v8: General Upgrade Steps.
Migrating from Traditional Architecture
See Traditional Architecture: Migration Overview.
Data Migration
See Traditional Architecture: Import and Catch Up with One Writer.
Code Migration
See Migrate the Boundary Before the Tables and Reconcile, Then Move Reads and Writes Separately.
Compatibility Notes
See Continue Evolving the Domain Model and v6 → v8: Breaking Changes Check.
Known Issues
See the Release Notes and Troubleshooting. Reproduce a failure against the exact pinned tag before applying a workaround.
Migration Checklist
Use the Traditional Architecture Completion Checklist or v6 → v8 Verification Checklist, then add environment-specific production admission evidence.
Rollback Plan
Use the selected guide's rollback procedure and the before/after-first-write distinction in Shared Completion Gates.
Unified Runtime Orchestration
See Runtime Orchestration Migration.
Removal of Versioned Snapshot Checkpoints
See v6 → v8: Versioned Snapshot Checkpoint Removal.
Atomic SnapshotStore Saves
See v6 → v8: Atomic SnapshotStore Saves.
Redis EventStore Canonical v2 Layout (introduced in v8.9.0)
See v6 → v8: Redis EventStore Canonical v2 Layout.
Mongo Ownership Guard
See v6 → v8: Mongo Ownership Guard.
Related Pages
| Page | Relationship |
|---|---|
| Migrating from Traditional Architecture | First adoption and traffic ownership |
| Migrate Wow v6 to v8 | Existing Wow platform/storage upgrade |
| Runtime Orchestration Migration | Unified lifecycle source migration |
| V9 Query Migration | V8.16.x to V9 query and SnapshotStore source migration |
| Runtime Lifecycle | Stable runtime model after migration |
| Troubleshooting | Evidence-first diagnosis when a gate fails |