Should I Upgrade This Dependency?
Most “it built yesterday, broke today” incidents trace back to an unplanned dependency bump. Run these five go/no-go gates before you change a version. Each gate is a hard stop: if the no-go condition is true, do not upgrade yet — fix the underlying cause first.
1 Security gate
Does the upgrade close a vulnerability you are actually exposed to?
The release patches a CVE in code paths your app reaches. Upgrade is justified on its own.
It is a major version with breaking changes and the patched CVE is not reachable from your usage. Prefer a minimal patch within your current major.
2 Semver gate
Is the bump within a safe version range?
Patch or minor (x.y.Z / x.Y.z) with green tests. Safe to proceed in normal flow.
Major (X.y.z) with removed/renamed APIs. Requires a migration plan and a dedicated branch, not a drive-by bump.
3 Peer-dependency gate
Do peer requirements still resolve?
Peer ranges overlap with the rest of the tree; lockfile resolves with no peer warnings.
The bump forces a peer conflict across multiple packages. Upgrade will cascade; coordinate or pin.
4 Lockfile & reproducibility gate
Can the upgrade be reproduced in CI from a clean cache?
Lockfile updated, integrity hashes present, CI install is deterministic.
You are editing package.json without regenerating the lockfile, or relying on a floating range. CI will drift.
5 Blast-radius gate
What breaks if the upgrade is wrong?
Well-tested library with a fast rollback path and feature-flagged usage.
It is a transitive core dependency with no test coverage and no staging gate. Schedule a controlled rollout.
Decision flow (top-down)
- Security gate fails the “go” test? Upgrade on its own branch, fast-follow.
- Semver says major? Write a migration note; do not bundle with feature work.
- Peer or lockfile gates fail? Stop and reconcile the dependency tree first.
- Blast-radius high and untested? Gate behind a flag and ship to staging only.
- All gates green? Bump, regenerate the lockfile, let CI confirm, then merge.
Still stuck on a specific error? Pair this checklist with the Debug Decision Worksheet and the open common developer errors dataset (JSON).