version: "1.0.0" name: dependency-update description: "Guide for safely updating project dependencies. Use when asked to update packages, upgrade dependencies, or check for outdated libraries." source: "Internal engineering practices" domain: "maintenance" level: "foundational" agents: ["backend-dev", "security", "security-validation"] created_date: "2026-04-27" last_validated: "" validated_by: "" status: "draft" allowed-tools: shell

Dependency Update

Overview

A structured process for safely updating project dependencies. Updates are categorized by risk level and applied in controlled batches with verification at each step.

Key Concepts

Semantic Versioning Risk Tiers

• Patch (x.x.X): Bug fixes only. Safe to batch.
• Minor (x.X.0): New features, backward compatible. Update in small batches.
• Major (X.0.0): Breaking changes. Update one at a time. Read the changelog.

Patterns & Techniques

Safe Update Process

Step 1: Audit

# Python
pip list --outdated
 
# JavaScript
npm outdated

Step 2: Categorize — Group by risk tier (patch, minor, major).

Step 3: Update per batch

1. Update the dependency
2. cd hastelib && hatch build -t wheel — check build
3. cd hastelib && hatch run test:pytest — check behavior
4. cd ui && npm run lint — check for new warnings
5. If tests fail, investigate and fix or revert

Step 4: Security check — Scan for known vulnerabilities.

Step 5: Commit — One commit per logical group:

chore(deps): update [package] from vX to vY

Decision Framework

Common Pitfalls

• Updating everything at once — If tests fail, you can't tell which update caused it
• Skipping the changelog — Major updates often require code changes
• Ignoring transitive dependencies — A safe direct dep can pull in a vulnerable transitive dep