Git Semantic Versioning – How Semantic Versioning Fits into a Development Timeline

Should I release these packages with different version names using Semantic Versioning? In my opinion, yes, but what about the naming of these different versions?

You should not change the version unless your code changes. However, your current approach of appending the library version works fine under the rules of Semantic Versioning, but you have to use a + sign to add the library dependency:

• 1.0.0
• 1.0.0+json-c-0.10

For realeasing, and assuming your package name is purestjson this gives:

• purestjson-1.0.0
• purestjson-1.0.0+json-c-0.10

Rationale: Semantic Versioning states in rule 10:

Build metadata MAY be denoted by appending a plus sign and a series of dot separated identifiers immediately following the patch or pre-release version. Identifiers MUST comprise only ASCII alphanumerics and hyphen [0-9A-Za-z-]. Identifiers MUST NOT be empty. Build metadata SHOULD be ignored when determining version precedence. Thus two versions that differ only in the build metadata, have the same precedence. Examples: 1.0.0-alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85.

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.