CORE GUIDE
Dependency and migration verification
Dependency upgrades and data or schema migrations require verification across compatibility, rollout and rollback boundaries because a locally correct code change can fail when versions or persisted state differ in production.
Mental model
Think of a migration as a change to the compatibility envelope. You must prove which old and new states can coexist, how data moves, what happens during partial rollout, and how the system recovers if the change is reversed.
Why it matters
AI coding agents are especially prone to treating an upgrade as editing package versions until tests pass. Production systems often have lockfiles, generated clients, database state, caches, multiple deploy versions and external consumers. Verification must cover the transition, not only the destination.
01
Verify the transition matrix, not just the final build
Record the before and after versions or schemas, identify persisted or external contracts, and test forward compatibility, mixed-version operation and rollback where relevant. Run migrations on representative data, inspect generated diffs and lockfiles, and make irreversible transformations explicit. Require deployment evidence such as canary checks or post-migration assertions for high-risk changes.
02
Example: schema migration passes tests but breaks rolling deploy
A service renames a database column and updates all code references. Unit tests pass against a freshly migrated database, but the first new instance deploys while old instances are still serving and they fail on the renamed field. A compatibility-aware migration adds the new column first, dual-reads during rollout, backfills data, then removes the old column only after the fleet converges.
Common failure modes
- Verifying only a clean install instead of the real upgrade path.
- Changing schema and application assumptions atomically when deployment is rolling.
- Calling rollback safe without testing what happens to already-migrated data.
Engineering heuristics
- Write down supported version/state combinations before shipping the migration.
- Test with representative persisted data and mixed-version boundaries.
- Separate reversible rollout steps from irreversible cleanup.
Takeaways
- 01Migration correctness is about transitions between states.
- 02Passing the final build does not prove rolling compatibility.
- 03Rollback and data semantics belong in the original change design.
Reading evidence
This records actions you actually took; it does not claim mastery, proficiency, or certification.
Used in
This Concept is reused across these canonical learning paths.
Related concepts from the Knowledge Graph
These relationships come from the canonical graph, not a separate Guide taxonomy.