How does semantic versioning work in practice, and when do I bump major?

Short answer: semantic versioning is a promise about compatibility for people who depend on your public API. Bump based on what that promise covers.

The rules (semver 2.0.0)

• MAJOR (2.0.0): you made incompatible changes to the public API.
• MINOR (1.3.0): you added functionality in a backward compatible way.
• PATCH (1.2.4): you made backward compatible bug fixes. Versions below 1.0.0 are considered unstable; anything may change.

What counts as the public API

Whatever users are meant to rely on: exported functions and types, CLI flags, configuration keys, HTTP endpoints and response formats, database migrations for an installable product. Internal modules are not part of it unless you documented them.

Typical examples

• Removing or renaming a function, changing a parameter type or a default behaviour: major.
• Adding an optional parameter or a new function: minor.
• Fixing a crash without changing documented behaviour: patch.
• Deprecating something (still working, with a warning): usually minor; the removal later is major.

Practical habits

1. Keep a CHANGELOG with sections for added, changed, deprecated, removed and fixed.
2. Tag releases in Git (v1.4.2).
3. Deprecate before removing, and say what to use instead.
4. Use pre-release tags for testing, such as 2.0.0-beta.1.
5. Automate checks where possible, such as type or API diff tools.

Pitfalls

• Calling a breaking change a patch because it is "small".
• Bumping major for every release; consumers stop trusting the number.
• Applications and websites do not always need strict semver; many use date-based or build-number versions instead. Pick one scheme and state it.

When in doubt, ask: could an existing user's code or setup break after upgrading? If yes, it is major.