Should I upgrade a dependency to a new major version?

Upgrade a major version when there is a reason: a security fix, an end of support date, or a feature you need. Do it on a branch, read the changelog, and test. A major bump is allowed to break compatibility, so never accept one blindly from an automated tool.

What the version numbers promise

Under semantic versioning, a patch release holds backward compatible bug fixes, a minor release adds backward compatible features, and a major release marks backward incompatible changes. The specification also says that versions starting with zero are for initial development, where anything may change at any time.

Reasons to upgrade now

• The current major no longer receives security fixes.
• The vulnerability you care about is only fixed in the new major.
• Another dependency of yours now requires it.
• The runtime you are moving to needs it.

Reasons to wait

• Nothing is wrong with the version you run and it is still supported.
• The release is days old and early adopters are still reporting regressions.
• You lack tests around the code that uses the library.

Waiting is fine for a while. Waiting with no plan is how teams end up three majors behind and facing a painful jump.

A safe upgrade routine

1. Read the release notes for every major in between, not just the last one.
2. Create a branch and upgrade only this package.
3. Fix compile errors and deprecation warnings.
4. Run the full test suite and a manual pass over the features that use the library.
5. Deploy gradually if you can, and keep the old version one revert away.

When the new major is the only fix

Sometimes a vulnerability is fixed only in a newer major. Check whether your usage touches the vulnerable code first. If it does, the upgrade is a security task, with a deadline. If it does not, record that finding and schedule the upgrade normally.

Keep majors small

Upgrading often, in small steps, costs less than one big migration every few years. A scheduled dependency update slot each month usually beats heroic catch up projects.

Quick check

Sources

• Semantic Versioning

Last reviewed: 19 October 2026.