Versioning

It is useful to define a versioning for a project and document it. Users of your system may then extract information about changes simply by comparing version numbers.

Simple Versioning Scheme

We find the following versioning scheme simple but effective.

The version consists of a major, a minor and a micro number (e.g. 1.23.42 ). For snapshot versions (current builds before a release), the qualifier SNAPSHOT is appended (e.g. 1.23.42-SNAPSHOT ).

The parts of the version number have the following meaning.

Part Example Description
major number 1.23.42 API changed in a way not compatible with the previous version. For instance the Java version has changed, classes or packages have been removed because of architectural changes.
Tip: To help the users of your library you will want to offer a migration path. While working on issues it may proof useful to tag those changes with the keywords break.api, break.runtime, or break.removed. Please refer to Breaking Tags in Bugzilla Keywords for details on those keywords.
minor number 1.23.42 API has changed but is compatible with the previous version. New features may have been added, features may also have been deprecated, but no feature has been changed or altered so that depending code would break.
Tip: If an issue marks an existing feature as deprecated it may be useful to tag it with the keyword break.deprecated.
micro number 1.23.42 Patch release. No API changes. No runtime behavior changed according to the documentation.
Tip: If a bug is fixed where you feel your community has implemented a well-known-workaround and this workaround may after the fix have negative effects on those environments using the work around, it may be useful to tag the issue with the keyword break.runtime.

Major Release Zero

For major releases with version number zero we handle the Simple Versioning Scheme less strict. The reason for this is that at the beginning of a project, the development is often experimental. Things work, some things don't, some need small changes, some bigger ones.

To respect this evolutionary design we do not want to change the major release version until we regard the product as stable and shippable. Therefore, for projects in their major version number zero state compatible changes are reflected by changing the micro version, while changing the minor version may include new features and the removal of obsolete features. Incompatible changes are mentioned in the breaking news report.

Resources

You find more information on versioning here:

Hint for Maven users: The versions-maven-plugin may proof useful in managing version numbers for multi projects.