We find it useful to define a versioning for our project and document it. Users of our products may then extract information about changes simply by comparing version numbers and look them up in the release reports or on our issue tracking server.
Release information provided by a Bugzilla server can be easily added with the use of our Issues Maven Plugin.
The administration of versions and milestones on a Bugzilla server can be done very conveniently with the Bugzilla Maven Plugin. Please have a look at the best practices on using this plugin.
Versioning Rules
Simple Versioning Scheme
We use the following versioning scheme.
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.To help users of our library we work on offering a migration path. While working on issues we 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.If an issue marks an existing feature as deprecated we tag it with the keyword break.deprecated. |
| micro number | 1.23.42 | Patch release. No API changes. No runtime behaviour changed according to the documentation.If a bug is fixed where we feel the community has implemented a well-known-workaround and this workaround may – after the fix – have negative effects on those environments using the work around, we 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
- APR’s Version Numbering, Apache Portable Runtime (APR) Project
- Software versioning @ wikipedia
- This article was originally posted 2010 on our project website.
Hint for Maven users: The Versions Maven Plugin may proof useful in managing version numbers for multi projects.
Edit, 10/2012: There is a specification for this form of versioning called semantic versioning. This specification gives a deeper insight into the versioning scheme and its consequences than our short blog post here:
- Semantic Versioning
- Semantic Versioning -Technical Whitepaper – (PDF) OSGi Alliance
- About Versions – posted at Software Simplexity by Peter Kriens
