doc/VersionNotes

   1 Preamble
   2 --------
   3
   4 Barry is primarily intended to be a library, for any application to
   5 access Blackberry devices.  There will be an OpenSync module built
   6 on top of this, plus some command line utilities, and a GUI,
   7 but initially Barry is a library, and must be versioned accordingly.
   8
   9 Additional applications built on top of Barry may be versioned separately.
  10
  11 Since Barry is a library, applications need to know which versions
  12 they are compatible with.  Unix has a version number scheme for this
  13 already.
  14
  15
  16 History
  17 -------
  18
  19 Initially, I had tried to use the old Linux kernel style of version
  20 numbering.  One series of version numbers for development, and one
  21 for "stable" releases.  Linux has since abandoned this versioning
  22 scheme, and after reality has bumped me about, I'm about to abandon
  23 it too.
  24
  25 The reason is that all of Barry's releases are generally stable.
  26 They are expected to work on all systems, even in the git tree.
  27 People run Barry from the git repositories regularly, and often
  28 the code in git is more stable or feature complete than the
  29 released tarball.
  30
  31 The goal of Barry's development style is to always be stable.
  32 Every commit should compile.  Every commit should work with all
  33 devices.  Every commit should be examined closely for security
  34 issues or buffer overflows.  It should be possible to take a
  35 snapshot of Barry's source tree at any time and use it.
  36
  37 Indeed, Barry's versioning over the past few years since 2005
  38 has indicated this philosophy.  Only 16 versions have been released,
  39 from 0.0.1 to 0.16.  The development has been linear, and while
  40 there have been some large changes to the library and tools (such
  41 as the introduction of optional threads) this has not impacted
  42 the stability of the library.  Most issues in Barry arrise from
  43 udev permissions problems or interactions with unknown parts of
  44 the Blackberry firmware.  There was only one release that was
  45 specifically to fix a bug in Barry itself.  (Version 0.11 which
  46 fixed a null pointer bug in 0.10, and which was released the
  47 day after.)
  48
  49 So in the end, Barry is retaining a versioning feature it does
  50 not need (unstable and stable lines of development) and ignoring
  51 a feature it does need (library versions that indicate backward
  52 compatibility).
  53
  54
  55 New Direction
  56 -------------
  57
  58 To fix this, we're going back to 3 number versioning, but with a
  59 twist:
  60
  61         logical.libmajor.libminor
  62
  63 Logical now becomes something of an advertisement.  When we have
  64 sufficient features, we can call it version 1.  Until then, we
  65 remain version 0.
  66
  67 Libmajor will start with the old minor, at 17.  It represents
  68 a compatible library.  All version 17 libraries are linkable to
  69 applications that depend on them.
  70
  71 Libminor will represent releases that do not affect binary compatibility.
  72
  73 So the first version using this new scheme will be version 0.17.0
  74 and the libbarry.so will be named libbarry.so.17.0.0, libbarry.17.0.1,
  75 etc.
  76
  77
  78 Managing Version Numbers
  79 ------------------------
  80
  81 Any changes in the following areas require a bump in libmajor:
  82
  83         - removing:
  84                 - a standalone function call
  85                 - a member function
  86                 - a member variable from a class
  87                 - a global variable
  88         - changing:
  89                 - the arguments in an API call
  90                 - the size or name of a member variable
  91                 - the size or name or a global variable
  92                 - the virtual-ness of a member function
  93         - adding:
  94                 - a member variable to the middle of the class
  95         - moving:
  96                 - a public element from one namespace to another
  97
  98
  99 Any changes in the following areas only require a bump in libminor:
 100
 101         - adding:
 102                 - a non-virtual member function to a class
 103                 - a standalone function call
 104                 - a global variable
 105                 - an entirely brand new class
 106         - changing:
 107                 - the internal implementation of a non-inline function
 108                 - any class or function, in any way, that is not BXEXPORTed
 109                 - any non-library code
 110
 111 As you can see, most of the time we'll be bumping the libmajor
 112 version anyway, just like we've been bumping the minor.  But at
 113 least now, distros and library users can separate Barry library
 114 versions, and safely install multiple versions of the Barry
 115 library on their system at the same time.
 116
 117 This version scheme will in no way impact the freedom to change the API.
 118 If the API needs to be updated, we'll bump the libmajor version with
 119 impunity.
 120
 121 If you have comments or suggestions or bug reports with regard to
 122 Barry versioning, please post to the barry-devel mailing list.
 123
 124 Chris Frey <cdfrey@foursquare.net>
 125 October 2010
 126