H.6 Migration

A broad change is not one operation. It is a population moving from an old supported state to a new supported state while ordinary development continues. The migration is done only when the old state is no longer an accidental path.

Choose Responsibility And Shape The Transition

Begin with H.6.1 Evolution Models. A provider-led migration, consumer-led upgrade, coordinated cohort, or hybrid assigns implementation, scheduling, validation, and repair differently. Then use H.6.2 Migration Strategy to choose an atomic change, expand-migrate-contract sequence, shards, or cohorts from the real compatibility and recovery boundary—not from repository size alone.¹

Consider a schema-backed client used by hundreds of services. The provider can first add the new field while preserving the old one, then migrate consumers in cohorts, and finally remove the old field. That longitudinal case crosses source, generated interfaces, deployed skew, and owner capacity, so one large commit would not make the runtime transition atomic.

Operate One Observable State

H.6.3 Migration Automation supplies codemods, structured build-file editors, AST transforms, generators, and graph analysis. Deterministic transformations and representative semantic review make automation evidence; they do not make the tool the decision authority.

H.6.4 Progress Control maintains the consumer inventory, cohorts, blockers, exceptions, entry and completion criteria, anti-backsliding, and stop decision. The same schema-client migration should show which services still read the old field, which deployment cohorts are safe, and where new old-state use is blocked.

This is a bounded transformation expected to finish. A standard that remains in force and evolves over time follows H.8.3 Policy Lifecycle instead, even when the standard initially needs migration work.

H.6.5 Cleanup completes the program by removing shims, flags, old APIs, exceptions, temporary tooling, dashboards, and stale guidance after evidence shows supported consumers have moved. If the old field remains accepted forever, the organization created a second architecture rather than completing a migration.

Footnotes

1. Software Engineering at Google — Ch. 22: Large-Scale Changes — staged large-scale change, migration control, and completion ↩