Major, minor, and patch bumps (API)
Under Semantic Versioning, a patch bump (1.0.0 → 1.0.1) signals a bug fix that does not change the API contract. A minor bump (1.0.0 → 1.1.0) signals new functionality that is backward compatible — existing consumers can continue using the API without changes. A major bump (1.0.0 → 2.0.0) signals at least one breaking change that requires consumers to update their integration.
Formula
Decision matrix:
Bug fix, no contract change → patch
New optional field, new endpoint → minor
Removed field, changed type, renamed endpoint → major
New required field on existing request → major (breaks existing clients)Why it matters in practice
The key judgment is "would an existing consumer break?" — not "did I change a lot?" A single field removal in a deeply nested response object is a MAJOR change if consumers rely on that field. Adding 100 new optional fields is a MINOR change if all existing consumers can safely ignore unknown fields. The test for backward compatibility must be made from the consumer's perspective, not the provider's.
Common mistakes
- •Bumping MINOR for what is actually a MAJOR change — "it's just a small change" justification for avoiding a MAJOR bump creates silent breakage in consumers.
- •Not testing backward compatibility with existing client code before declaring a release MINOR-safe.
- •Bumping MAJOR too eagerly for changes that are actually MINOR — this trains consumers to ignore MAJOR bumps.