Migration Guide
There are two primary migration paths. First-time Wow adoption is about domain boundaries, data modeling, and traffic cutover. Wow v6 → v8 is about the exact source-tag platform delta, source compatibility, and storage-format cutovers. A system already on Wow v8 with custom runtime lifecycle ownership also needs the runtime-orchestration migration track inside the v8 path; it is not a third business or data migration. Choose the primary path first; do not combine both into one release.
Choose a Migration Path
| Current state | Goal | Read | Keep out of scope |
|---|---|---|---|
| Traditional CRUD, transaction scripts, or direct database writes | Adopt Wow CQRS and event sourcing incrementally | Migrating from Traditional Architecture | Wow v6 version-compatibility assumptions |
| Wow v6 on its exact pinned platform | Wow v8 on its pinned target platform | Migrate Wow v6 to v8 | Redesigning every business boundary |
| Wow v8 with custom Dispatcher, MessageBus, or Spring lifecycle integration | Current unified WowRuntime | Runtime Orchestration Migration | Rewriting business data |
Documentation Boundaries
| Page | Answers | Primary source |
|---|---|---|
| Traditional architecture | How do we establish commands, aggregates, events, and state from CRUD, then move traffic safely? | CreateOrder.kt:31-64, Order.kt:55-137 |
| v6 → v8 | How do we align the exact v6 platform baseline with the pinned v8 target and handle storage and API breaks? | v6.21.5 versions, v8.0.0 Release, current versions |
| Runtime orchestration | How do we converge multiple lifecycle owners on one WowRuntime? | WowAutoConfiguration.kt:118-152 |
Shared Completion Gates
Both primary paths and the runtime-orchestration track must advance on evidence. A process that merely starts is not yet migrated.
- Scope: Fix the bounded context, dataset, source version, target version, and explicit exclusions.
- Baseline: Record tests, event/snapshot counts, critical business metrics, and a restorable backup.
- Verification: Run unit and integration tests, per-aggregate reconciliation, representative replay, and real startup/shutdown.
- Rollout: Validate one instance or a small traffic slice first, including rollback after new writes.
- Closure: Remove old data, writers, compatibility code, and temporary synchronization only after the observation window.
Legacy Link Navigation
The topics formerly on this page moved to Migrating from Traditional Architecture, Migrate Wow v6 to v8, and Runtime Orchestration Migration. The headings and aliases below retain every deep link from the original page; continue to the linked page after arrival.
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 Traditional Architecture: Migrate the Boundary Before the Tables and Reconcile, Then Move Reads and Writes Separately.
Compatibility Notes
See Traditional Architecture: Continue Evolving the Domain Model and v6 → v8: Breaking Changes Check.
Known Issues
See the Release Notes and Troubleshooting.
Migration Checklist
See the Traditional Architecture Completion Checklist or the v6 → v8 Verification Checklist.
Rollback Plan
See the Shared Completion Gates on this page and the cutover and rollback steps on the selected migration page.
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-time Wow adoption |
| Migrate Wow v6 to v8 | Platform upgrade for existing Wow systems |
| Runtime Orchestration Migration | v8 lifecycle extension migration |
| Troubleshooting | Investigation entry point when verification fails |