Release and migration analysis

Release Notes & Migration Analysis

When to Use

Use during decision, design, diagnosis, planning, and implementation of any dependency upgrade. Never treat Semantic Versioning (semver) as a guarantee of compatibility—minor and patch releases frequently tighten TypeScript types, alter default behaviors, bump minimum runtimes, or fix bugs that callers inadvertently depended on.

Multi-Version Delta Analysis

When upgrading from version A to version B (e.g., 1.4.2 $\rightarrow$ 2.1.0 or 3.2.0 $\rightarrow$ 3.9.1), inspect the cumulative delta across every intermediate major, minor, and patch release (A, B], not only version B:

1. Official Sources First: Read upstream CHANGELOG.md, GitHub Releases, official migration guides (UPGRADING.md), security advisories (GHSA/CVE), and commit diffs when release notes are terse.
2. Distinguish Evidence Tiers:
   • Documented Breaking Change: Explicitly stated in upstream release notes or migration guides.
   • Proven Codebase Impact: Verified call sites, configs, or types in this repository matching the changed contract.
   • Assumed / Unverified Risk: Areas with dynamic reflection or terse upstream docs; flag explicitly for runtime testing.

Six Contract Surfaces to Evaluate

1. Runtime, Engine & Platform Floor

• Minimum Node.js (engines.node), PHP (require.php + ext-*), Python (requires-python), Rust (rust-version / MSRV), OS glibc/musl, and browserslist.
• Native addon ABI compatibility (N-API version, prebuilt binaries for darwin-arm64, linux-x64-gnu, linux-x64-musl, win32-x64).

2. Module Format, Packaging & Entrypoints

• CJS-to-ESM-only transitions ("type": "module", removal of main CJS fallback, changed exports subpath maps blocking deep pkg/lib/* imports).
• TypeScript declaration shifts: bundled .d.ts replacing @types/<pkg>, moduleResolution: "bundler" | "nodenext" requirements, or stricter generic inference.

3. Public API Signatures & Default Behavior

• Removed or renamed functions, classes, hooks, CLI flags, middleware signatures, or options keys.
• Silent default changes (strict mode enabled, timeout defaults changed, SSL verification enforced, cookie SameSite/CORS defaults, pagination limits, exception hierarchies, or async rejection contracts).

4. Configuration & Build Tooling Contracts

• Changed config schemas (ESLint flat config eslint.config.js, Vite/Rollup/Webpack plugin hooks, TSConfig flags, PostCSS/Tailwind config, PHPUnit XML schema, pyproject.toml sections) and implicitly read environment variables.

5. Serialization, Wire Protocol & Persistent Data Compatibility

• Database schema/migration changes, cache payloads, session formats, queue job payloads, or JWT/crypto formats affecting in-flight jobs or rolling deployments. If the upgrade mutates persistent data or cache formats, downgrading the package binary alone will not restore previous state.

6. Lifecycle Scripts & Supply-Chain Provenance

• New preinstall/install/postinstall scripts, Composer allow-plugins, or build scripts (build.rs, setup.py). Verify official upstream provenance when a package is deprecated or renamed.

Target Version Selection & Stepping

Weigh LTS support window, ecosystem peer readiness, security urgency, and migration cost. When crossing multiple majors (v2 $\rightarrow$ v5), check whether stepping through intermediate majors (v2 $\rightarrow$ v3 $\rightarrow$ v4 $\rightarrow$ v5) is required for deprecation bridges, codemods, or schema migrations.