Semver Rules

Version format

• MAJOR — incompatible API changes
• MINOR — new backward-compatible functionality
• PATCH — backward-compatible bug fixes

Pre-1.0 note: if the current version is 0.x.y, anything goes — MINOR bumps are common for breaking changes. Once past 1.0.0, the rules below apply strictly.

What counts as a MAJOR bump (breaking change)

Breaking changes are any modifications that could cause a consumer of the library to experience a compile error, runtime error, or behavior change without changing their own code.

Examples:

• Removing a public function, class, method, or constant
• Renaming a public function, class, method, or constant
• Changing a function signature (adding required parameters, removing parameters, changing parameter types, changing return type)
• Changing observable behavior that callers depend on (e.g., error types thrown, event names emitted, return value shape)
• Changing a required configuration key or its accepted values
• Dropping support for a runtime/language version that was previously supported
• Removing or renaming a publicly exported module path

When in doubt, prefer a MAJOR bump over a MINOR. It’s better to signal a breaking change than to silently break consumers.

What counts as a MINOR bump (new feature)

• Adding a new public function, class, method, or constant
• Adding optional parameters to an existing function (with backward-compatible defaults)
• Implementing a new protocol/interface that doesn’t affect existing ones
• Adding new configuration keys with sensible defaults
• Deprecating (but not removing) a public API — removal comes in a future MAJOR

What counts as a PATCH bump

• Fixing a bug where behavior was incorrect relative to documented intent
• Improving performance without changing the public API
• Internal refactoring with no external observable difference
• Documentation updates
• Dependency updates that don’t change the library’s own public surface
• CI/CD, test, tooling changes
• Security fixes that don’t break the API

Multiple changes — precedence

When a release contains a mix of change types, the highest precedence wins:

One breaking change + ten new features = MAJOR bump.

First release (no prior tags)

Default to 1.0.0 regardless of what’s in the diff. Inform the user.

Edge cases