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 outdated to identify packages with major version changes

• Read existing tmp/UPGRADES.md if 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 dates

The 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

Dev Dependencies

Transitive

Major version updates needed in parent packages (not directly actionable).

Scoring

Action:

• plan : Ready to upgrade - version is mature and migration path is clear

• wait : Not ready - version too fresh, still in beta, or ecosystem not ready

• blocked : Dependency conflict prevents upgrade

• skip : 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, avoid

• early : x.1.x - early adopter territory

• stable : x.2.x - stabilizing, okay to plan

• mature : x.3.x+ - battle-tested, safe to upgrade

Urgency (based on current version status, NOT new version existence):

• critical : Known security vulnerability in current version

• high : Current version deprecated/EOL/no longer receiving patches

• medium : Current version in maintenance mode (security only)

• low : Current version still actively supported

Difficulty:

• trivial : Drop-in replacement, no code changes

• easy : Config/import changes only

• moderate : Some code changes required

• hard : Significant refactor needed

• major : 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