A structured checklist for upgrading npm, pip, Cargo, or similar dependency managers without breaking production. This covers changelog analysis, semver risk assessment, lockfile handling, and smoke testing so that routine dependency updates do not become sources of production incidents.
Use cases
- Monthly routine dependency updates that your CI runs automatically but which occasionally introduce breaking changes
- Applying an urgent security patch where you need to upgrade quickly while minimizing the risk of introducing a production incident
- Migrating to a major new version of a framework where the changelog indicates breaking changes and a migration guide exists
- Upgrading a transitive dependency that you do not directly control but which has a new version with a CVE fix
- Evaluating whether to update a dependency that has not been updated in over a year and has accumulated several major version jumps
Key features
- Read the package changelog and release notes for the target version, noting all breaking changes, deprecated API removals, and behavior changes
- Assess semver impact: patch updates are typically safe, minor updates are usually safe with testing, major updates require reviewing breaking changes and migration guides
- Update the lockfile and run the full test suite locally, capturing which tests fail and whether failures are related to the upgrade or pre-existing
- Check your codebase for usage of deprecated or removed APIs using linter rules, deprecation warnings, or grep for the old API patterns
- Pin exact versions in your lockfile before merging, run integration tests against the upgraded versions, and document any configuration or API changes required in the upgrade notes
When to Use This Skill
- When applying security patches where speed is important but you still need to verify you are not introducing new failures
- When performing regular dependency maintenance and wanting a consistent, reproducible process
- When major version upgrades require careful migration planning before touching production
Expected Output
A dependency upgrade PR with changelog analysis, semver risk classification, test results, and documented migration steps for any API or behavior changes.
Frequently Asked Questions
- What is the safest way to handle transitive dependency upgrades?
- Use tools like npm-check-updates, dependabot, or Renovate that analyze the full dependency tree. For transitive dependencies with CVEs, verify that upgrading the direct dependency actually pulls in the patched transitive and that the patched version does not break your direct dependency.
- How do I test a dependency upgrade without a comprehensive test suite?
- Focus on smoke testing the most critical user-facing paths. If you do not have a test suite, at minimum verify that the application starts, the main feature flows work, and check the browser console for errors. Document what was tested.
- Should I update dependencies proactively or wait for problems?
- Proactive updates are safer because they keep you on supported versions and reduce the blast radius of each upgrade. Waiting allows technical debt to accumulate and makes each upgrade more risky. Monthly minor updates beat annual major migrations.
Related
Related
3 Indexed items
Safe refactoring
Executes refactoring changes in small, test-backed steps so behavior is preserved while structure improves. Each refactoring operation—rename, extract, inline, move—is validated by the test suite before proceeding to the next, preventing the common pattern of refactoring into subtle behavioral regressions that are only caught in production.
Incident response
Structured process for handling production incidents from detection to resolution and post-mortem. Covers severity assessment using P0-P3 grading, team coordination with a designated incident commander, communication templates for stakeholders and users, and structured post-mortem requirements to drive organizational learning from every significant outage.
Security review for AI-generated code
Reviews AI-generated code for security failure modes that AI assistants commonly miss: prompt injection risks, credential exposure, dependency vulnerabilities, insecure deserialization, and access control gaps. This skill catches what agents miss when they optimize for functionality over safety, especially in code that handles user input, authentication, or external data.