MAJOR: Breaking Changes
You'll learn when to increment the major version number and what qualifies as a breaking change in your package's API.
What Is a Breaking Change?
In semantic versioning (MAJOR.MINOR.PATCH), the MAJOR version increments when you introduce changes that break backward compatibility. If existing code using your package will throw errors, behave differently, or require modification after updating, that's a breaking change.
Think of it like changing the shape of a puzzle piece. Code that relied on the old shape won't fit anymore without adjustments.
Examples of Breaking Changes
- Removing a function or method: If you delete an exported function, any code calling it will break.
- Renaming exports: Changing
export function oldName()toexport function newName()forces users to update all references. - Changing function signatures: Removing parameters, reordering them, or changing return types can break existing usage.
- Altering behavior: If a function previously returned a number but now returns a string, downstream code may fail.
- Raising minimum requirements: Requiring a newer Node.js version or dropping support for an older one breaks environments that can't upgrade.
What Isn't a Breaking Change
Adding new features (MINOR), fixing bugs (PATCH), or internal refactoring that doesn't affect the public API are not breaking changes. The key question: "Will existing code continue to work without modification?"
Why It Matters
When you bump from 2.x.x to 3.0.0, you're signaling to users: "Read the changelog carefully before upgrading." This honesty prevents unexpected production failures and maintains trust in your package.
Key Takeaway: Increment the MAJOR version whenever changes force users to modify their code, rename imports, or adjust how they use your package—backward compatibility is the deciding factor.