Major, Minor, Patch — What Each Number Means

Understanding MAJOR.MINOR.PATCH

Semantic Versioning uses three numbers to communicate the nature of changes between releases.

The Three Components

Component	Position	Increment When...	Example
MAJOR	First	Incompatible API changes	1.0.0 → 2.0.0
MINOR	Second	Backwards-compatible features	1.0.0 → 1.1.0
PATCH	Third	Backwards-compatible bug fixes	1.0.0 → 1.0.1

Reset Rules

When you increment a higher component, lower components reset to zero:

• Bump MAJOR: 1.4.7 → 2.0.0 (minor and patch reset)
• Bump MINOR: 1.4.7 → 1.5.0 (patch resets)
• Bump PATCH: 1.4.7 → 1.4.8 (nothing resets)

What Counts as a "Breaking Change"?

In general, a breaking change is anything that could make existing code stop working:

• Removing a public function or method
• Changing a function's signature (parameters, return type)
• Renaming or removing a configuration option
• Changing default behavior that users depend on
• Dropping support for a runtime version (e.g., no longer supporting Node.js 16)

What Counts as a "Feature"?

A minor version bump is appropriate for:

• Adding a new function, method, or endpoint
• Adding a new optional parameter with a default value
• Introducing a new configuration option
• Deprecating (but not removing) existing functionality

What Counts as a "Bug Fix"?

A patch version bump is for:

• Fixing incorrect behavior that deviated from documentation
• Security patches that do not change the API
• Performance improvements with no API changes
• Correcting typos in error messages

The 0.x Exception

Before version 1.0.0, the API is considered unstable. The rules are relaxed: any change can happen in any release. This is why ^0.2.3 is treated differently from ^1.2.3.

In Practice

Most ecosystems rely on these conventions:

• npm: Caret (^) assumes minor/patch are safe
• Cargo: Same convention as npm
• Go: Import path changes for major versions (v2, v3)