Migration Guide Generator

When an API is deprecated and a replacement ships, consumers need a clear path from old calls to new ones. A Migration Guide Generator turns paired API specs, deprecation notices, and known breaking changes into a draft migration guide: prerequisites, mapping tables, code before/after examples, rollout notes, and a checklist for cutover.

The audience is a developer-experience writer who owns migration guides. The model produces the first pass. The writer still validates behavior against the real APIs, adjusts tone and product voice, and publishes only when the draft is accurate. The system does not replace editorial judgment; it compresses the time from “we shipped a replacement” to “a structured draft exists.”

This sits in the software domain at the retire stage, with a speed outcome: faster, more consistent migration documentation when libraries, services, or platform APIs are sunsetting. It pairs naturally with cleanup work such as Codebase Cleanup Agent, discovery work such as Dead Code Detector, and inventory work such as Dependency Usage Analyzer, which identify what still depends on the old surface so the guide can prioritize real call sites.

The draft quality depends on explicit, comparable inputs. At minimum:

• Deprecated API specification: OpenAPI, GraphQL schema, protobuf, or equivalent, including operation IDs, paths, request and response shapes, auth requirements, and error models still in force during the deprecation window.
• Replacement API specification: the same form of schema for the successor, including new names, versions, and any required headers or SDKs.
• Deprecation metadata: sunset dates, supported overlap period, links to changelogs, and whether dual-running is allowed.
• Known breaking-change notes: renames, removed fields, semantic shifts (for example status codes that mean something different), and auth or tenancy changes.
• Consumer context (optional but useful): whether the guide is for external partners, internal services, or both; preferred languages for examples; and any house style for headings and warning callouts.

Without both the old and the new API specs, the generator must return empty output. A single schema, a marketing blurb, or a changelog alone is not enough to map requests and responses safely. Empty output is the correct failure mode: it prevents inventing endpoints, fabricating field mappings, or guessing breaking changes.

When specs exist but are incomplete (missing error models, ambiguous versioning), the draft should mark gaps explicitly rather than fill them with plausible fiction. Uncertain mappings belong in a “Needs verification” section for the writer, not as confident instructions in the consumer-facing body.

Given both specs and deprecation metadata, the model builds a structured outline and fills each section from the paired contracts:

1. Scope and audience: what is retiring, what replaces it, and who must migrate (public SDK users, internal services, partners).
2. Timeline: deprecation date, last date old calls are accepted, and recommended migration window.
3. Concept mapping: old resource or RPC names to new ones, with notes where concepts do not map 1:1.
4. Endpoint and operation mapping: method and path (or RPC) pairs, query and path parameters, and headers that changed.
5. Payload mapping: request and response field tables, type changes, required vs optional shifts, and renamed enums.
6. Auth and tenancy: token scopes, API keys, org or workspace identifiers, and any new consent or permission steps.
7. Error handling: old error codes to new ones, and where clients must change retry or user-facing messaging.
8. Code examples: minimal before/after snippets in the languages the writer requested, staying faithful to the schemas.
9. Rollout and coexistence: feature flags, dual-write or dual-read patterns if documented, and how to verify success.
10. Cutover checklist: practical steps (update clients, run contract tests, remove old credentials, archive old docs).

The generator should prefer tables for mappings and short paragraphs for rationale. Long narrative without a mapping table is hard for consumers to scan and hard for the writer to diff against the specs.

The model drafts; DX still publishes. That boundary matters for trust and for legal or partner commitments tied to deprecation dates.

Review typically covers:

• Contract fidelity: every mapped field and status code checked against both specs and against a live or staging environment if available.
• Semantic honesty: renames are not treated as drop-in replacements when meaning changed; the guide must say so.
• Example correctness: snippets compile or run against the new client; secrets and tenant IDs stay as placeholders.
• Voice and structure: house style, warning callouts, and links to support or status pages.
• Audience split: internal guides may include runbooks and owner contacts; external guides stay within the public contract and published SLAs.

Until review is done, the artifact remains a draft. Publishing is a human action: merge to the docs site, update the deprecation banner on the old API page, and announce through the usual channels. The generator does not auto-publish or silently overwrite an existing guide.

When specs are missing or one side is unavailable, empty output forces the team to fetch complete contracts before any prose appears. That is preferable to a polished-looking guide that invents a migration path.

A strong draft is boring in the best way: clear mappings, dated timeline, verified examples, and an explicit list of items the writer must still confirm. It names the old and new versions, cites the schema sources used for the draft, and keeps consumer instructions separate from internal rollout notes.

A weak draft invents endpoints, collapses breaking changes into “rename only,” or writes essay-length motivation without a mapping table. It also fails when it proceeds without both specs. Empty output in that case is success for the system’s safety rules, not a product bug.

Related tooling helps keep the guide honest after publication: usage analysis from Dependency Usage Analyzer shows which packages still call the old API; Dead Code Detector and Codebase Cleanup Agent support removing obsolete clients once traffic and docs have moved.

Treat the generator as a structured first author, not a source of truth. Keep old and new specs versioned next to the guide so regeneration is reproducible when the replacement API still changes during beta. Re-run the draft when either schema changes, then diff the new draft against the published guide instead of editing blindly.

Prefer one guide per major migration (for example v1 to v2 of a public API) rather than a mega-doc covering unrelated retirements. Split internal and external audiences when the checklist or examples diverge. For multi-language SDKs, generate example sections per language only when the SDK docs or typed clients are available as inputs; otherwise leave language sections as stubs marked for the writer.

Finally, align the guide’s sunset language with the deprecation banner and changelog. Consumers notice when dates or “supported until” wording disagree across surfaces. The generator can draft consistent wording from the same metadata; the writer confirms it matches what product and legal already approved.