Semantic versioning explained for library authors

Semantic Versioning for Library Authors

Semantic versioning (semver) is a contract with your users. Every version number communicates the type of change and whether upgrading is safe. Breaking this contract destroys trust faster than any bug.

The Three Numbers

• MAJOR — Breaking change. Existing code may stop working after upgrading. Users must take action.
• MINOR — New functionality added in a backward-compatible way. Safe to upgrade automatically.
• PATCH — Bug fix. No new functionality, no breaking changes. Always safe to upgrade.

What Counts as a Breaking Change

// Breaking — removing a public function (bump MAJOR)
- export function legacyFormat(data) {...}

// Breaking — changing a function signature (bump MAJOR)
- getUserById(id: string): User
+ getUserById(id: string, options: Options): User  // options has no default

// NOT breaking — adding an optional parameter with a default
+ getUserById(id: string, options: Options = {}): User  // safe MINOR bump

// NOT breaking — adding a new export (bump MINOR)
+ export function getUserByEmail(email: string): User

Version Ranges for Consumers

In package.json, ^2.1.0 means "accept any 2.x.x >= 2.1.0 but not 3.x.x." This works only if library authors follow semver precisely. One missed MAJOR bump can silently break every dependent package pinned with a caret range.