[geos-devel] C library versioning confusion

[Sandro Santilli]

I've noticed there's some confusion with versioning of the
C library. Hoping to do something useful I moved documentation
about how to set version directly in Version.txt

The confusion I see is with CAPI_INTERFACE_* values.

For 3.9.0, like for any other .0 release, the CAPI_INTERFACE_REVISION
should be set to 0, because we'll be adding interfaces (functions)
in such releases. From documentation:

   - Adding interfaces, bump CURRENT/AGE, set REVISION to 0.

Now, last 3.8 release (3.8.1) came out with these values:

    CAPI_INTERFACE_CURRENT=14
    CAPI_INTERFACE_REVISION=3
    CAPI_INTERFACE_AGE=13

This means 3.9.0 should be:

    CAPI_INTERFACE_CURRENT=15 <--- we added functions!
    CAPI_INTERFACE_REVISION=0 <-- first revision of this new interface
    CAPI_INTERFACE_AGE=14 <-- we're still compatible with
                              functions from interface n.1

Instead, in current 3.9 branch we have something which makes
no sense to me:

    CAPI_INTERFACE_CURRENT=17
    CAPI_INTERFACE_REVISION=2
    CAPI_INTERFACE_AGE=16

I guess this was done because for some reason the documentation
for version was changed at some point to be inaccurate (ie: "always
increment revision"). I've now committed the correct documentation
back directly into Version.txt, and would like to use the correct
versioning for 3.9.0 final, unless there's some specific reason why
we're "giving numbers".

Note also the 3.8 branch has some issues with CAPI_INTERFACE_REVISION
as it seemed to start at 1 for 3.8.0 so there's now a mismatch from
patch level and REVISION (there should usually not be)

--strk;