Preamble -------- Barry is primarily intended to be a library, for any application to access Blackberry devices. There will be an OpenSync module built on top of this, plus some command line utilities, and a GUI, but initially Barry is a library, and must be versioned accordingly. Additional applications built on top of Barry may be versioned separately. Since Barry is a library, applications need to know which versions they are compatible with. Unix has a version number scheme for this already. History ------- Initially, I had tried to use the old Linux kernel style of version numbering. One series of version numbers for development, and one for "stable" releases. Linux has since abandoned this versioning scheme, and after reality has bumped me about, I'm about to abandon it too. The reason is that all of Barry's releases are generally stable. They are expected to work on all systems, even in the git tree. People run Barry from the git repositories regularly, and often the code in git is more stable or feature complete than the released tarball. The goal of Barry's development style is to always be stable. Every commit should compile. Every commit should work with all devices. Every commit should be examined closely for security issues or buffer overflows. It should be possible to take a snapshot of Barry's source tree at any time and use it. Indeed, Barry's versioning over the past few years since 2005 has indicated this philosophy. Only 16 versions have been released, from 0.0.1 to 0.16. The development has been linear, and while there have been some large changes to the library and tools (such as the introduction of optional threads) this has not impacted the stability of the library. Most issues in Barry arrise from udev permissions problems or interactions with unknown parts of the Blackberry firmware. There was only one release that was specifically to fix a bug in Barry itself. (Version 0.11 which fixed a null pointer bug in 0.10, and which was released the day after.) So in the end, Barry is retaining a versioning feature it does not need (unstable and stable lines of development) and ignoring a feature it does need (library versions that indicate backward compatibility). New Direction ------------- To fix this, we're going back to 3 number versioning, but with a twist: logical.libmajor.libminor Logical now becomes something of an advertisement. When we have sufficient features, we can call it version 1. Until then, we remain version 0. Libmajor will start with the old minor, at 17. It represents a compatible library. All version 17 libraries are linkable to applications that depend on them. Libminor will represent releases that do not affect binary compatibility. So the first version using this new scheme will be version 0.17.0 and the libbarry.so will be named libbarry.so.17.0.0, libbarry.17.0.1, etc. Managing Version Numbers ------------------------ Any changes in the following areas require a bump in libmajor: - removing: - a standalone function call - a member function - a member variable from a class - a global variable - changing: - the arguments in an API call - the size or name of a member variable - the size or name or a global variable - the virtual-ness of a member function - adding: - a member variable to the middle of the class - moving: - a public element from one namespace to another Any changes in the following areas only require a bump in libminor: - adding: - a non-virtual member function to a class - a standalone function call - a global variable - an entirely brand new class - changing: - the internal implementation of a non-inline function - any class or function, in any way, that is not BXEXPORTed - any non-library code As you can see, most of the time we'll be bumping the libmajor version anyway, just like we've been bumping the minor. But at least now, distros and library users can separate Barry library versions, and safely install multiple versions of the Barry library on their system at the same time. This version scheme will in no way impact the freedom to change the API. If the API needs to be updated, we'll bump the libmajor version with impunity. If you have comments or suggestions or bug reports with regard to Barry versioning, please post to the barry-devel mailing list. Chris Frey <cdfrey@foursquare.net> October 2010