In http://semver.org/ —which in my perception seems to be the most widely used convention in versioning— it is recommended to increase the major version number when a change that breaks/modify the API is introduced.

There are two related scenarios I don't see how to apply this guideline though:

  1. What if my code doesn't offer any API? How should I version my code?
  2. What if my code starts offering an API in a late stage of its development?
  • 7
    Point 1 of the spec states: Software using Semantic Versioning MUST declare a public API. This API could be declared in the code itself or exist strictly in documentation. However it is done, it should be precise and comprehensive. So I guess the answer is you're not technically using SemVer so it's entirely up to you. – Ant P Sep 2 '14 at 19:55
  • Check this article which proposes a good solution for apps that don't offer any API, like desktop apps: softwareengineering.stackexchange.com/a/357887/269082 – ferit Sep 23 '17 at 10:43

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.

  • 1
    A lot of software produced by Microsoft development tools has A.B.C.D format, where A.B are the "common" major/minor version numbers, and C.D encodes the date/time when the software was built. – MZB Sep 3 '14 at 4:41
  • I love the semantics of the π versioning system. – Ogier Schelvis Mar 14 at 8:43

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.