Research breaking changes

Migration & Breaking-Change Intelligence

Changelogs frequently omit subtle behavioral changes—altered default timeouts, stricter validation, changed error classes, or modified return semantics. When researching an upgrade or comparing versions, combine release notes with direct commit/diff inspection.

Workflow

1. Map the version span and release history:
   • Identify the exact current version (vFrom) and target version (vTo), plus all intermediate major and minor releases.
   • Read CHANGELOG.md, GitHub Releases, and official migration guides across every intermediate major version (e.g., upgrading v2 -> v5 requires checking v3, v4, and v5 breaking notes).
2. Inspect diffs on public entry points and types:
   • Compare exported TypeScript definitions (.d.ts), public classes/functions, and configuration schemas between vFrom and vTo.
   • Check for:
     • Removed or renamed exports, methods, and options.
     • Changed default values (e.g., retry: true -> false, timeout: 0 -> 30000, strict: false -> true).
     • Sync-to-async signature changes or Node/runtime minimum version bumps (engines field).
3. Search post-release issues for regression reports:
   • Check issues opened shortly after vTo shipped. Early adopters often report undocumented breaking changes, memory regressions, or bundler incompatibilities before docs are updated.
4. Produce a concrete migration impact map:
   • Cross-reference every upstream breaking change against our codebase's actual call sites (grep / AST search).
   • Classify each impact as:
     • Zero-impact: Affects APIs we do not call.
     • Mechanical codemod: Simple rename or signature adjustment across $N$ call sites.
     • Behavioral / semantic shift: Requires adapter changes, config pinning, or new regression tests.
   • Hand off the verified impact map to the dependency upgrade specialist or implementing developer.