Migration Guides and Breaking Changes
Migration guides and breaking-change notes should let a reader decide whether they are affected, make the required change, and verify that their workflow still works. Lead with the affected versions and behavior, then show the action. “Improved the user schema” is release-note optimism, not a migration instruction.
Separate the change announcement from the procedure. A changelog can point to the guide; the guide must carry the prerequisites, compatibility window, failure conditions, and recovery implications needed to finish the work.
TL;DR
- Name source/target versions, affected workflows, and exceptions.
- Show before/after behavior with complete executable or reproducible examples.
- State overlap and removal dates as real approved policy, or clearly fictional teaching assumptions.
- Test old/new clients and ambiguous inputs during coexistence.
- Include verification and a bounded rollback or repair route.
Quick Example
This complete Python 3.12 teaching adapter models a fictional rename from full_name to display_name. It accepts either spelling during an invented overlap period, rejects conflicting values, and validates the runtime type. It is not a deployed API policy or an announced TekStache change.
The guide for this hypothetical change would tell new writers to send display_name, explain how older writers remain supported, and define removal only after an approved policy and evidence review. An adapter accepting old requests does not prove older clients can parse a changed response.
Core Concepts
Compatibility has several surfaces
Source compatibility concerns compiled or imported client code; wire compatibility concerns serialized messages; semantic compatibility concerns expected behavior. Google AIP-180 distinguishes those dimensions and warns that apparent additions can still affect clients. Scope its API guidance to the relevant protocol and consumer model rather than presenting it as a universal guarantee.
A rename can be removal plus addition
Document what happens to both spellings while they coexist, including conflicts, defaults, and response behavior. Silent precedence can hide incorrect writes. The fixture chooses explicit rejection for differing values; that is a declared design decision, not a requirement imposed by every API standard.
Versions communicate policy, not proof
Semantic Versioning describes major/minor/patch meaning for a declared public API. A version number does not establish that an implementation follows its promise. Include representative compatibility tests and concrete behavior changes even when the release follows a familiar versioning scheme.
A Guide That Supports an Actual Change
For the rename example, list request writers, response readers, generated clients, saved payloads, and background jobs separately. Updating the visible form may leave an import job sending the old field. Track remaining usage with a defined observation method before removing support.
Put the action near the impact. “Replace the outgoing request key; keep reading both response forms until the server rollout completes” is useful only if that is the actual supported sequence. Review the order with the implementation owner and test it against both versions.
If the change cannot overlap safely, explain the required coordinated window and its consequences. Do not invent a zero-downtime route to make the documentation feel friendly. A precise stop condition is more useful than a promise the system cannot keep.
Best Practices
Test the guide from a clean starting state
Use an environment matching the documented source version and prerequisites. Follow the written steps without relying on hidden local configuration. Record missing commands, permissions, and expected outputs so the guide works for another reader.
Keep examples small and complete
Use fictional data and show the whole changed boundary. Include a negative case that would catch a plausible incomplete migration. A snippet showing only the new field cannot demonstrate coexistence or conflict behavior.
Name the point of difficult reversal
State when new writes or data transformations make a code rollback insufficient. Preserve the source data or a reviewed repair route where appropriate. Reverting a package version does not automatically reverse a changed persisted representation.
Common Mistakes
Bad: Publish a removal date that no owner approved.
Correct: Use the approved policy and distinguish illustrative dates from real commitments.
Bad: Describe a breaking rename as a cosmetic cleanup.
Correct: Explain the affected request/response behavior and required client action.
Bad: Verify only the new client against the new server.
Correct: Exercise supported old/new combinations and the intended rollout sequence.
FAQ
Is every migration guide a breaking change?
No. A guide may cover configuration, platform, or data movement with varying compatibility. State the actual affected boundary.
Should the changelog contain every step?
Keep the announcement concise and link to a complete procedure when the action needs prerequisites, ordering, or verification.
Can a major version replace a guide?
It signals policy for users who follow that versioning model. It does not tell them what code or data must change.
What remains beyond this adapter test?
Real clients, response compatibility, rollout telemetry, approved dates, persisted data, and operational recovery remain separate evidence.
Related Topics
- Release Notes & Changelogs — Separate announcements from migration procedures.
- Data Contracts and Schema Evolution — Plan compatibility and overlap.
- OpenAPI and API Contract Generation — Check generated contracts and change detection.