Dependency upgrades and compatibility

Upgrade flow (skill-flow-block)

  [ Inventory: direct deps + graph + peer / optional ]
                    │
                    ▼
         ┌──────────────────────┐
         →SemVer target band   │──── Read CHANGELOG / releases;
         →& breaking matrix    →     majors assume wider tests or contracts
         └──────────────────────┘
                    │
                    ▼
         ┌──────────────────────┐
         →Lockfile: same       │──── npm / pnpm / pip / Go modules —
         →resolver in CI+local →     forbid “package.json only—drift
         └──────────────────────┘
                    │
                    ▼
         ┌──────────────────────┐
         →Migration: codemod / │──── Feature flags; deprecations with timeline
         →canary / staging obs →
         └──────────────────────┘
                    │
                    ▼
              [ Merge │ keep rollback: prior lock snapshot / tag / revert cmd ]

SemVer and breaking changes

Patches and minors can still break builds via tighter types, runtime differences, or implicit behavior; majors should assume public API shifts and official migration guides.

• Read changelogs for Breaking, deprecation windows, and minimum runtime requirements.
• Peers: framework plugins, engines, native ABI, and OS matrices together.
• Deprecated APIs: document replacements and removal targets—avoid silent debt.

npm-check-updates usage and batch upgrade strategy:

# npm-check-updates: detect upgradeable dependencies
# Install
npm install -g npm-check-updates

# View all upgradeable dependencies (no package.json changes)
npx ncu

# Upgrade patch versions only
npx ncu --target patch -u
npm install

# Upgrade minor versions only
npx ncu --target minor -u
npm install

# Upgrade a specific package to major version (handle separately)
npx ncu -u react react-dom
npm install

# View dependency tree diff (before and after upgrade)
npm ls --depth=2 > deps-before.txt
npx ncu -u && npm install
npm ls --depth=2 > deps-after.txt
diff deps-before.txt deps-after.txt

# Batch upgrade strategy (recommended order)
# Batch 1: patch (automerge, lowest risk)
# Batch 2: minor (merge after smoke test)
# Batch 3: major (separate PR + migration guide + extended tests)
# Security CVE: isolated PR, use urgent channel

Lockfiles and resolver consistency

When switching registries or mirrors, keep CI, containers, and developer machines on the same lockfile and install commands—otherwise you get “green locally, red in CI—resolution forks.

• Node: pick one of package-lock.json / pnpm-lock.yaml / yarn.lock; document npm ci-class commands and cache policy.
• Python: hashed requirements.txt or poetry.lock / uv.lock; avoid unlocked range-only upgrades.
• Go: complete go.sum; module proxy and GOPRIVATE with auth notes.

Migration, observability, and rollback

Breaking migrations should ship with codemods or staged adaptation; observe error rates and latency in staging or canaries, and define rollback to the prior lock artifact or image tag.

• Major bumps default to expanded tests or contract updates.
• Feature flags can isolate new dependency paths for fast disable.
• Record OS and language runtime compatibility for on-call.

Renovate configuration file example (patch automerge + major requires manual review):

// renovate.json — project root
{
  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
  "extends": ["config:recommended"],

  // Merge time window: weekday mornings (reduce noise)
  "schedule": ["before 9am on Monday through Friday"],

  "packageRules": [
    // patch: automerge (only when CI is fully green)
    {
      "matchUpdateTypes": ["patch"],
      "automerge": true,
      "automergeType": "pr",
      "requiredStatusChecks": ["CI / test", "CI / lint"]
    },
    // minor: auto-create PR, requires manual review
    {
      "matchUpdateTypes": ["minor"],
      "automerge": false,
      "labels": ["dependencies", "minor"]
    },
    // major: group into one PR with breaking-change label
    {
      "matchUpdateTypes": ["major"],
      "automerge": false,
      "groupName": "major dependencies",
      "labels": ["dependencies", "major", "breaking-change"]
    },
    // security vulnerabilities: immediate PR, skip time window
    {
      "matchCategories": ["security"],
      "schedule": "at any time",
      "automerge": false,
      "labels": ["security", "urgent"]
    }
  ],

  // lockfile maintenance: weekly update (when no version changes)
  "lockFileMaintenance": {
    "enabled": true,
    "schedule": ["before 6am on Monday"]
  }
}

SKILL snippet

---
name: dependency-upgrade
description: Assess dependency upgrades, SemVer, compatibility, and lockfile consistency
---
# Detection tools
- npm-check-updates: npx ncu (view) / npx ncu -u (update)
- Renovate: auto-create PRs, configurable automerge
- npm audit: npx npm audit (security vulnerability detection)

# Batch upgrade strategy
- Batch 1: patch → automerge (CI all green)
- Batch 2: minor → create PR, merge after smoke test
- Batch 3: major → separate PR + migration guide + extended tests
- Security CVE → isolated PR, urgent channel, skip time window

# Checklist
1. CHANGELOG: Breaking / deprecations / minimum runtime requirements
2. Peer dependencies: engines / framework plugins / native module ABI
3. Transitive deps: npm ls --depth=2 before/after diff
4. Lockfile: package-lock.json / pnpm-lock.yaml pick one and use consistently
5. CI and local use the same npm/pnpm major version

# Renovate automerge config key points
- patch: automerge: true, requiredStatusChecks: [CI/test]
- minor: automerge: false, manual review
- major: groupName grouping + breaking-change label
- lockFileMaintenance: weekly lockfile maintenance

# Rollback
- Record lock commit SHA / tag before upgrade
- Rollback command: git checkout <sha> -- package-lock.json && npm ci

Self-check checklist (page JS)

Pick ecosystem and bump level to generate a local memo (no network); trim to your stack before pasting into issues or PRs.