The Right Way to Think About Semantic Versioning

Last updated:

This has been circulating for a bit, and it matches how I always interpreted things:

The canonical way that "semantic versioning" is described is that the three numbers are for "major" updates, "minor" updates, and "revisions". But those aren't descriptive; they invite value judgements and don't have a firm definition.

The more useful way to think of the version numbers are for "breaking changes", "feature additions", and "bugfixes". Or, to be even more specific:

Bugfix

  • Code written against the old version WILL work with the new version.
  • Code written against the new version WILL work with the old version.

(Assuming that the code wasn't relying on undefined behavior.)

Feature

  • Code written against the old version WILL work with the new version.
  • Code written against the new version MIGHT NOT work with the old version.

Breaking

  • Code written against the old version MIGHT NOT work with the new version.
  • Code written against the new version MIGHT NOT work with the old version.

That's a simple, common-sense, objective way to determine which part of the version number you should increment. It helps your users figure out whether or not they might break, and it helps you avoid arguments about whether something is a "major" or "minor" change.

(a limited set of Markdown is supported)