Semantic Versioning for Eclipse Developers

Semantic Versioning for Eclipse Developers

Eclipse/OSGi has a strict versioning scheme consisting of 4 parts, separated by dots. This is well-known to Eclipse developers, and thus in the Eclipse/OSGi world the versioning problems are solved.

In the past few months references to the Semantic Versioning scheme became more and more frequent. It seems similar to the Eclipse versioning, but is not quite the same. Thus a small overview is in order. Here is a comparision of the version segments:

Eclipse Versioning Semantic Versioning
MAJOR MAJOR mandatory
.MINOR .MINOR mandatory
.SERVICE .PATCH mandatory

Valid Eclipse versions are i.e.: 0.9.0,, 2.0.0.beta-20100202-R32, 2.0.0

Valid Semantic versions are i.e.: 0.9.0+20100202.R32, 1.11.2-beta, 2.0.0-beta+20100202.R165, 2.0.0


The rules for incrementing the different version segments are more or less the same in both versioning schemes. These are the rules for Semantic Versioning:

  1. MAJOR version when you make incompatible API changes,
  2. MINOR version when you add functionality in a backwards-compatible manner, and
  3. PATCH version when you make backwards-compatible bug fixes.

The difference is the syntax with the qualifier/metadata information in the last segments of the versions. A qualifier is separated by a dot and can be almost any string. Compared to the qualifier, the prerelease ID and build metadata are separated by ‘-‘/’+’ and carry a bit more semantic information.

An Eclipse developer might view this as just another qualifier, but be aware that the specification of a prerelease ID and build metadata actually tells more about the contents of a version than just “any string”. You can let yourself inspire for choosing your qualifiers, but in the Eclipse world, you’ll always have the problem, that 2.0.0.beta > 2.0.0

The different separators make the versions syntactically incompatible.

About Semantic Versioning

The semantic versioning was proposed by Gravatar inventor and Github Cofounder Tom Preston-Werner. It is almost two years old, now in version 2.0.0, but got more public awareness only recently.

What about Maven?

Eclipse and Semantic Versioning  carry semantics in their versioning scheme, by being quite specific about when and how to increment which version segments.

Maven acknowledges the importance of versions, but is interested in them only for technical dependency resolution. Maven gives no semantic advice, and obviously it has to remain quite tolerant when interpreting versions. Maven can interpret semantic versions as well as Eclipse versions.

  • Ferry
    Posted at 3:50 pm, June 28, 2013

    The one true source of semantic versioning is here:

  • Ralf Sternberg
    Posted at 4:37 pm, June 28, 2013

    Do you follow semantic versioning rules in your projects? Which tools do you use to update version numbers and to ensure you don’t forget to increment the patch version after a relevant change?

  • Ferry
    Posted at 5:55 pm, June 28, 2013


    Bndtools (next version) will do this automatically for you 🙂
    See these posts:

  • Neil Bartlett
    Posted at 9:46 am, June 29, 2013

    Ralf: Bndtools includes lots of features for managing semantic versions. In the current development version, we have a baselining feature for APIs and bundles… this compares the project in the workspace against the previous release in a repository. It creates red X markers (with quick-fixes) when the API has changed without the version being bumped correctly.

    For example if I have API version 1.0.0 that has been released into the repo, and then I add a method to an interface in that API package. Bndtools will tell me that the package version must now be 1.1.0 because adding an method is a MINOR change. It will also do this for the Bundle-Version.

    We also understand the difference between “provider-implemented” and “consumer-implemented” interfaces. For example if you add a method to a consumer-implemented interface (annotated with @ConsumerType) then this is actually a MAJOR change.

  • Paul Verest
    Posted at 11:47 am, July 1, 2013

    Could you please give links to tool that help with semver in Eclipse.

  • Paul Verest
    Posted at 11:51 am, July 1, 2013

    For Maven there is Versions Maven Plugin
    Maven Release Plugin
    But I haven’t yet tried them with Tycho

  • Ralf Sternberg
    Posted at 5:28 pm, July 2, 2013

    Thanks Ferry and Neil, I’ll surely give Bndtools a try. Since I’ve learned about it in an EclipseCon tutorial I’m confident that this approach is superior to PDE. However, I’m not sure what it means to migrate existing PDE projects with a tycho/hudson build infrastructure to Bndtools. I’ll probably start with a pet project.

    Apart from that, the question that bothers me is the patch version. This segment should be incremented after a release when the first non-API change is made. I don’t want to update the patch version if the bundle is unchanged. How can I make sure not to forget to update the patch version when I make the first change? Does Bndtools help with this issue as well?