Migration Guide¶
Reference document — instantiates Compatibility Management
A dependent-facing document that turns a deprecation into something people can act on — what is going away, what replaces it, by when, and how to get an exception if they cannot move in time.
Migration Guide is the human-facing artifact that makes a version change actionable for the people who depend on the old one. A change can be permitted, signalled, and even automated on the provider's side and still fail in the field, because the dependents who must adapt their own systems do not know what changed, what to use instead, or by when. The guide closes that gap: it operationalises a deprecation into readable form — the specific things being retired, their replacements, the timeline, worked examples, and the warnings — and, crucially, it tells a dependent who cannot migrate in time what to do about it. Its distinctive quality is that it is written for the consumer, not the maintainer: its job is not to change the system but to change what the system's dependents know and can do.
Example¶
A national health-data programme is moving hospital integrations from the older HL7 v2 messaging standard to FHIR resources. The transformation machinery exists, but hundreds of independent hospital IT teams have to rewire their own interfaces — and they cannot all be phoned individually. So the programme publishes a migration guide.
It states the deprecation concretely: which v2 message types are being retired, the FHIR resource that replaces each, side-by-side examples of an old message and its new equivalent, and a dated timeline (v2 endpoints accepted through a ≈two-year sunset, read-only for six months after). And it publishes the exception path: a small rural clinic whose vendor will not ship a FHIR-capable update before the cutoff can apply for a documented extension — the contact, the evidence required, and the interim support that remains during the waiver. The guide moves no data and flips no switch; it is pure communication. But without it, the same technical cutover produces a wave of broken integrations from teams who were never told, in terms they could act on, what to change or how to buy time.
How it works¶
- Operationalise the deprecation. For each retired element, state its replacement, a worked before/after example, and the exact dates — turning "X is deprecated" into a task a dependent can actually complete.
- Write for the consumer's context. Address the person adapting their system: the errors they will see, the order to change things in, the gotchas — not the maintainer's internal rationale.
- Publish the exception route. Say explicitly what a dependent does when they cannot meet the deadline — who to contact, what qualifies for a waiver, what support persists meanwhile — so "we can't make it" has a governed answer rather than a broken integration.
- Keep it current. Version the guide with the change itself; a guide describing a timeline that has since moved is worse than none.
Tuning parameters¶
- Prescriptive vs. reference — a step-by-step "do exactly this" walkthrough versus a complete catalogue of every change. Prescriptive gets the common case moved fastest; reference serves the odd cases but can bury the main path.
- Timeline firmness — how hard the published dates are. Firm dates create real migration pressure but invite a flood of exception requests; soft dates are humane but let migration drift indefinitely.
- Exception generosity — how easy a waiver is to obtain. Lenient protects stragglers but can gut the deadline for everyone; strict holds the line but strands the genuinely stuck.
- Coverage depth — happy-path only versus edge cases and known failure modes. Depth serves more dependents but costs authoring effort and can obscure the main route.
When it helps, and when it misleads¶
Its strength is reach: one well-made document lets a change propagate to many independent dependents who cannot be coordinated individually, and the exception path gives the ones who cannot keep up a defined alternative to simply breaking. It is what turns a deprecation from an announcement into a migration people actually complete.
Its weaknesses are those of any document. A guide that covers only the maintainer's intended happy path leaves every dependent with a non-standard setup stranded exactly when they most need help — and those are the migrations that stall (the long tail of the real Python 2-to-3 move is the familiar case[1]: guides existed, yet the awkward projects dragged on for years). A guide also goes stale: dates slip, replacements change, and a confidently wrong instruction is worse than silence. The most consequential misuse is treating the guide as the whole migration strategy — publishing a document and assuming dependents will therefore move — when a guide only informs; it neither enforces the deadline (that is the support schedule) nor performs the change (that is the migration itself). The discipline is to version the guide with the change, write from the dependent's side rather than the maintainer's, and treat a rising volume of exception requests as evidence that the guide or the timeline needs work, not merely as waivers to grant.
How it implements the components¶
Migration Guide fills the components that communicate and govern the dependent's move, not the ones that perform it:
deprecation_policy— the guide operationalises it: what is being retired, what replaces it, on what timeline, made concrete and consumer-readable so the deprecation is usable rather than merely declared.exception_and_waiver_path— it publishes the governed route for dependents who cannot migrate within the window: who to contact, what qualifies, and what interim support remains.
It does not transform any data (Schema Migration), oblige the new version to keep accepting old inputs (support_window, fallback_or_graceful_degradation_rule — Backward Compatibility Policy), signal the change as a version number (Semantic Versioning), or set the binding end-of-life dates it merely relays (Support Lifecycle Schedule). This document tells dependents how to move; siblings hold the door, move the data, and set the clock.
Related¶
- Instantiates: Compatibility Management — Migration Guide is the communication layer that makes a compatibility change usable by the dependents who must act on it.
- Consumes: the end-of-life dates it relays are set upstream by a support schedule (Support Lifecycle Schedule); the transformation it points dependents toward is performed by Schema Migration.
- Sibling mechanisms: Schema Migration is its data-side counterpart — that moves records, this moves people; Backward Compatibility Policy is what buys dependents the time this guide tells them how to use. Support Lifecycle Schedule · Semantic Versioning · Compatibility Matrix
Editorial Notes¶
Form Classification¶
Form family: Representation, Specification & Plan
Rationale: Migration Guide operates as a non-executable information artifact that externalizes static or prospective structure because it a dependent-facing document that turns a deprecation into something people can act on — what is going away, what replaces it, by when, and how to get an exception if they cannot move in time.
Independent corroboration: The frozen evidence defines Migration Guide as 'A dependent-facing document that turns a deprecation into something people can act on — what is going away, what replaces it, by when, and how to get an exception if they cannot move in time', so its operative form is Representation, Specification & Plan.
Review outcome: Independent reviewer agreement; high confidence.
Origin Attribution¶
Primary origin: Computer Science & Software Engineering
Origin pattern: Cross-disciplinary synthesis
Present-day reach: Multi-domain
Rationale: Dependent-facing deprecation and migration guides are established software lifecycle documentation.
Related originating lineages:
- Organizational & Management Science — Change communication contributes timelines, exceptions, and stakeholder support.
Review resolution: Both independent reviews place the primary provenance in computer_science. The queued differences (alternate_origin_disagreement, origin_mode_disagreement, domain_reach_disagreement) concern secondary metadata, not primary lineage. The final retains organizational_management only where a reviewer supplied a formative-lineage rationale; downstream use or broad applicability by itself is not treated as origin. origin_mode=cross_disciplinary_synthesis because the supplied rationales identify formative contributions that are composed in the mechanism's present form. domain_reach=multi_domain records established application breadth separately from provenance. confidence=high preserves the more cautious evidence assessment. encyclopedia_synthesis=false records whether either reviewer identified deliberate corpus-level composition.
Review outcome: Reconciled after independent review; high confidence.
References¶
[1] Peterson, B. PEP 373 — Python 2.7 Release Schedule. Python Enhancement Proposals, Python Software Foundation (2008). Records a five-year extension of Python 2.7 support because some users could not yet migrate and vendors still had to support Python 2 for years. registry ↩