Software versioning is magic. Think about the different versions of Windows or Star Wars movies. Well, the latter is not really software versioning but it shows that the issue is very general. In the case of Java, versioning is not that complex. First of all, the version of Java we use now is 9. The previous version was 1.8, before that 1.7, and so on, down to 1.0. Earlier versions of Java were called Oak but that is history. After all, that is, who can tell what Java 2 was?

Fortunately, when we create a Java application, the situation is simpler. There has been a suggestion from Oracle, from the time of Java 1.3, about how to version JARs:

http://docs.oracle.com/javase/7/docs/technotes/guides/extensions/versioning.html

This document distinguishes between specification version and implementation version. If the specification of a JAR content changes, the code has to behave differently from how it was behaving till then; the specification version should change. If the specification is not changed but the implementation does--for example, when we fix a bug--then the implementation version changes.

In practice, nobody has used this scheme, although it is a brilliant idea to separate the implementation and specification versions, at least, in theory. I even bet that most of your colleagues have not even ever heard about this versioning. What we use in practice is semantic versioning.

Semantic versioning (http://semver.org/) mixes the specification and implementation versions into one single version number triplet. This triplet has the format of mmp, that is:

• m: major version number
• m: minor version number
• p: patch number

The specification says that these numbers start with zero and increase by one. If the major number is zero, it means that the software is still in development. In this state, the API is not stable and may change without a new major version number. The major version number gets to 1 when the software is released. Later it has to be increased when the API of the application (library) has changed from the previous version and the application is not backward compatible with the previous version. The minor version number is increased when the change effects only the implementation but the change is significant, perhaps, even the API is also changing but in a backward-compatible manner. The patch version is increased when some bug is fixed, but the change is not major and the API does not change. The minor and the patch levels have to be reset to zero if any version number in the triplet in front of any of them is increased: major version number increase resets both minor and patch version; minor version number increase resets patch number.

This way, semantic versioning keeps the first element of the triplet for the specification version. The minor is a mix of the specification and implementation versions. A patch version change is clearly an implementation version change.

In addition to these, semantic versioning allows appending a pre-release string, such as -RC1 and -RC2. It also allows the appending of metadata, such as a date after a plus sign, for example, +20160120 as a date.

The use of semantic versioning helps those that use the software to easily spot compatible versions and to see which version is older and which is newer.