dependency-update

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

Update Type	Risk	Strategy
Patch	Low	Batch all, update together
Minor (well-known pkg)	Low-Med	Small batches of 3-5
Minor (niche pkg)	Medium	One at a time, check changelog
Major	High	One at a time, read migration guide
Security fix	Critical	Update immediately, regardless of type

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