Major Version Upgrade Analysis
Identify packages with major version upgrades available and assess whether upgrading is advisable.
Scope: Major versions only. Minor/patch updates are handled automatically by the daily audit script.
Instructions
- Run
pnpm outdatedto identify packages with major version changes - Read existing
tmp/UPGRADES.mdif it exists (preserve previous decisions/notes) - For each major version upgrade, assess:
- Stability of new version (see Maturity Assessment below) - Support status of current version (still maintained? security patches?) - Breaking changes and migration effort
- Write findings to
tmp/UPGRADES.md
Maturity Assessment
Before recommending any upgrade, check the new version's maturity:
pnpm view <package> dist-tags --json # Is "latest" stable or beta?
pnpm view <package> versions --json # Version history
pnpm view <package> time --json # Release datesThe minor version is the key signal - it indicates how many release cycles the major has been through:
x.0.x= Just released, avoid. Ecosystem still finding bugs.x.1.x= Early adopter phase. Only if you need a specific feature.x.2.x= Stabilizing. Reasonable to start planning.x.3.x+= Battle-tested. Safe to upgrade.
Red flags:
- Only beta/rc/canary releases for new major
- New major released < 1 month ago
- Major version with only.0.x patches (no minor releases yet)
- Changelog full of breaking change fixes post-release
Check npm release date: pnpm view <package> time --json | grep "5.0.0" to see when major was released.
Output Format
Write to tmp/UPGRADES.md:
# Major Version Upgrades
Last checked: YYYY-MM-DD
## Direct Dependencies
| Action | Package | Current | Latest Stable | Maturity | Urgency | Difficulty | Notes |
|--------|---------|---------|---------------|----------|---------|------------|-------|
| plan | zod | 3.23 | 4.3.5 | mature | low | moderate | x.3 = safe; [Migration](link) |
| wait | next-auth | 4.24 | 5.0-beta | beta | low | major | No stable release yet |
| wait | some-lib | 2.8 | 3.0.4 | fresh | low | easy | x.0 = wait for 3.2+ |
| wait | other-lib | 1.5 | 2.1.3 | early | low | moderate | x.1 = early adopter territory |
| plan | date-fns | 3.6 | 4.4.0 | mature | low | easy | x.4 = battle-tested |
| blocked | react | 18.3 | 19.2.1 | stable | low | hard | x.2 but blocked by next-auth |
## Dev Dependencies
| Action | Package | Current | Latest Stable | Maturity | Urgency | Difficulty | Notes |
|--------|---------|---------|---------------|----------|---------|------------|-------|
| plan | vite | 6.4 | 7.3 | mature | low | easy | Dev tooling only |
## Transitive
Major version updates needed in parent packages (not directly actionable).
| Package | Current | Latest | Via | Notes |
|---------|---------|--------|-----|-------|
| preact | 10.x | 11.x | next-auth | Will resolve when next-auth updated |Scoring
Action:
plan: Ready to upgrade - version is mature and migration path is clearwait: Not ready - version too fresh, still in beta, or ecosystem not readyblocked: Dependency conflict prevents upgradeskip: Intentionally staying on current version (document reason)
Maturity (based on minor version):
beta: Only pre-release versions available (no stable x.0.0 yet)fresh: x.0.x - just released, avoidearly: x.1.x - early adopter territorystable: x.2.x - stabilizing, okay to planmature: x.3.x+ - battle-tested, safe to upgrade
Urgency (based on current version status, NOT new version existence):
critical: Known security vulnerability in current versionhigh: Current version deprecated/EOL/no longer receiving patchesmedium: Current version in maintenance mode (security only)low: Current version still actively supported
Difficulty:
trivial: Drop-in replacement, no code changeseasy: Config/import changes onlymoderate: Some code changes requiredhard: Significant refactor neededmajor: Full migration/rewrite
Important
- Skip minor/patch updates - the audit script handles those
- Always check maturity before recommending an upgrade
- "Latest exists" ≠ "should upgrade" - new majors need time to stabilize
- Preserve existing entries - update status, don't remove previous decisions
- Check release dates - a 5.0.1 from last week is very different from 5.0.1 from 6 months ago