2, 3 or 4 digit iMesh version number

[Jason Kraftcheck]

Mark Miller wrote:
> Hi All,
> 
> Last week we talked about the fact that, technically speaking, we should
> only ever need a 2 digit version number for iMesh because it is really
> just an interface specification. Other than the header file itself,
> there is no real code to version. However, we agreed that a 3rd, patch
> digit which ordinarily applies only to bug fix releases of code
> underpinning an interface, gives us finer control over the version
> number and has value just for that reason.
> 
> I'd like to raise the possibility of a 4th digit.
> 
> In Silo and HDF5, a 4th digit is used solely for the release process
> itself. Typically, the release process does NOT got smoothly the first
> time out. So, we acknowledge that by creating 'release candidates' and
> tagging them such as Silo-4.7.1-pre1. If during the release process
> (testing on various platforms) bugs are found. Those bugs are
> immediately fixed and a new release candidate is created called
> 4.7.1-pre2. This process iterates until everything is stable everywhere.
> Then, the 'preX' nomenclature is removed, the release candidate becomes
> the release and the final 4.7.1 release is made.
> 
> I know of at least one or two points in our recent ITAPS history where
> we've experienced a similar sequence of events with the iMesh.h header
> file causing it to have to be immediately modified and everyone updating
> to that version.
> 
> Now, we could just opt to use the 3rd digit for this process. That may
> result in that digit changing more frequently than 'users' would expect
> but would otherwise I think be fine.
> 

My primary concern is that we have two "values": one indicating an
incompatible change to the interface and one indicating extensions to the
interface that would not break code compiled to use some other version with
the same first "value".  So in that sense, two numbers would be sufficient.
 However, the version numbers also have other connotations.  For example, in
practice we may want the first "value" that indicates incompatible changes
to be composed of two numbers.  If for similar reasons we don't want to
change the N numbers composing the "value" to indicates an incompatible
change, then the first "value" will need one more number.

After reading what I wrote, I think than an example might be better.  Let's
assume that we have API version with three numbers: A.B.C.  An increment of
either A or B indicate that an incompatible API change happened (function
removed, function signature changed, constant or enum *values* changed,
changing a typedef, etc.).  An increment of C indicates a extension (adding
a new function or constant, adding a new value to the end of an enum, etc.)
 If we release a broken 1.1.0 API, such that we must release a new one with
corrections and *if* it is not acceptable to call it 1.2.0, then we need a
fourth number.

- jason