API Semantic Versioning – Why Declare a Public API?

You hesitate because you don't want to make semantic versioning, you want to make "advertisement supporting versioning". You expect a version number "2.0" to tell the world that you have a bunch of new cool features in your library now, not that you changed the API. That's ok (many software companies and/or developers do that). IMHO you have the following options:

• stick to semantic versioning and live with the fact that you have to change the version number to 2.0.0
• change your versioning scheme to 4 numbers. "1.1.7.3" is your version now, "1.2.0.0" the next one after changing the API, and "2.0.0.0" the first one of the "completely new 2.x product family"
• make your fix backwards compatible (so don't change the functionality of next, just add the valid and current functions). Then you can use "1.8.0" as the next version number. If you think changing the behaviour of next is really important, do it in 2.0.0.

Semver is mostly concerned about versioning libraries and packages in a manner that avoids dependency hell, in it's various incarnations. However, the idea behind Semver can be extended to all kinds of programs – any piece of code has some kind of user interface, or it is pretty useless.

• A programming library or web service has an API.
• Consumer software might have a GUI.
• Command line programs have a set of switches and options.
• Configuration files are also an user interface.

Using the example of consumer software, such as a word processor:

• Increment the patch number when you ship a bug fix, e.g.: “fixed bug where application always crashes at 00:00 PM on Tuesdays”.
• Increment the minor version number when adding a new feature, e.g.: “added support for underlined text”.
• Increment the major version when you significantly overhaul the user interface, or rewrite all internals. E.g.: “Toolbars use too much screen estate. The UI is now provided through touch gestures only” – such a change would break existing workflows.

However, many problems which Semver tries to solve do not exist outside of the area of dependency management. In consumer applications, the version is not only a version, but also a marketing asset.

• Firefox and Chrome release new versions comparatively frequently, and increment their major version number at each release. This results in ridiculously high version numbers (both are currently in their 30s). A browser with a higher version number must simply be better than a browser with a lower version number, right?

• The major version number of Apple's operating system OS X has become part of the name (X is 10 in Roman numerals), making the minor version number the effective major version number.

• The Ubuntu operating system uses a year.month.patchlevel versioning scheme. This makes it easy to remember how old your OS is, but makes it much more difficult to figure out which versions are compatible, and how long support for each version lasts.

• The Linux kernel bumped the version number from 2.6.39 to 3.0.0, because the 39 was getting a bit large, and to commemorate Linux' 20th anniversary.

• Donald Knuth's legendary TeX typesetting system uses a version number that, as of version 3, converges to π by adding another digit at each release: 3.14159265…. This signifies how the system is getting closer to perfection. Similarly, the Metafont system converges to e: 2.7182818….

So, many applications are not well served by Semver. Pick a versioning scheme that's good for your users (regardless of whether these users are fellow programmers or consumers), and keep it consistent.