Update and simply SO versioning policy (#339)

This mirrors OpenEXR PR
[1498](AcademySoftwareFoundation/openexr#1498).

This change retires the "libtool" versioning scheme and adopts a policy of appending the MAJOR.MINOR.PATCH software release name to the SONAME to form the real name of the shared library.

The SOVERSION is specified via the OPENEXR_LIB_SOVERSION setting in CMakeLists.txt and is the single number that increments whenever, and only when, the ABI changes in non-backwards-compatible ways. In practice, this corresponds to major and minor releases.

The resulting real shared library file names look like, for example, libOpenEXR.so.31.3.2.0, where libOpenEXR.so.31 is the SONAME and .3.2.0 identifies the corresponding software release.

This naming scheme helps reinforce the correspondence between the shared library's real file name and the software release it corresponds to, more so than would be indicated by a single increasing number.

By OpenEXR project policy and discussion of the technical steering committee, the additional versioning information in the libtool versioning scheme is too confusing and error-prone to follow, without offering additional practical benefit.

Documentation is in CMakeLists.txt and in docs/install.rst.

Signed-off-by: Cary Phillips <[email protected]>

CMakeLists.txt

@@ -21,28 +21,17 @@ set(IMATH_VERSION_RELEASE_TYPE "-dev" CACHE STRING "Extra version tag string for
 set(IMATH_VERSION ${Imath_VERSION})
 set(IMATH_VERSION_API "${Imath_VERSION_MAJOR}_${Imath_VERSION_MINOR}")
 
-# Library/shared-object version using libtool versioning policy.
-# See https://www.gnu.org/software/libtool/manual/html_node/Updating-version-info.html
+# The SOVERSION (i.e. numerical component of SONAME) tracks the ABI
+# version. Increment this number whenever, and only when, the ABI changes in
+# non-backwards-compatible ways.
 #
-# Library API version (CMake's library VERSION attribute) is of the
-# form CURRENT.REVISION.AGE; the CMake SOVERSION attribute corresonds
-# to just CURRENT. These produce a .so and a symlink symlink, e.g.:
-# libImath-3_1.so.29 -> libImath-3_1.so.29.0.0
-#                 ^                     ^  ^ ^
-#                 |                     |  | |
-#                 CURRENT               |  | AGE
-#                                       |  REVISION 
-#                                       CURRENT
-# When updating:
-#   1. no API change: CURRENT.REVISION+1.AGE
-#   2. API added:     CURRENT+1.0.AGE+1
-#   3. API changed:   CURRENT+1.0.0
-#
-set(IMATH_LIBTOOL_CURRENT 29)
-set(IMATH_LIBTOOL_REVISION 0)
-set(IMATH_LIBTOOL_AGE 0)
-set(IMATH_LIB_VERSION "${IMATH_LIBTOOL_CURRENT}.${IMATH_LIBTOOL_REVISION}.${IMATH_LIBTOOL_AGE}")
-set(IMATH_LIB_SOVERSION ${IMATH_LIBTOOL_CURRENT})
+# The OpenEXR project policy is to append the library version 
+# "major.minor.patch" to the SONAME to form the real shared library name.  
+# For example, in "libImath.so.31.3.2.0", "libImath.so.31" is the SONAME
+# and ".3.2.0" identifies the corresponding library release.
+
+set(IMATH_LIB_SOVERSION 30)
+set(IMATH_LIB_VERSION "${IMATH_LIB_SOVERSION}.${IMATH_VERSION}") # e.g. "30.3.2.0"
 
 # ImathSetup.cmake declares all the configuration variables visible
 # in cmake-gui or similar and the rest of the global

CONTRIBUTING.md

@@ -10,8 +10,7 @@ explains our contribution process and procedures:
 * [Legal Requirements](#Legal-Requirements)
 * [Development Workflow](#Development-Workflow)
 * [Coding Style](#Coding-Style)
-* [Versioning Policy](#Versioning-Policy)
-* [Creating a Release](#Creating-a-Release)
+* [Versioning Policy and Release Process](#Versioning-Policy-and-Release-Process)
 
 Imath is a sub-project of
 [OpenEXR](https://github.com/AcademySoftwareFoundation/openexr) and
@@ -316,7 +315,7 @@ library.
 
 The test should should be run, via:
 
-    make test
+    % make test
 
 before submitting a pull request.
 
@@ -422,28 +421,9 @@ For public APIs, use Doxygen-style comments (start with `///`), such as:
         float foo;  ///< Doxygen comments on same line look like this
     }
 
-## Versioning Policy
+## Versioning Policy and Release Process
 
-Imath uses [semantic versioning](https://semver.org), which labels
-each version with three numbers: ``major.minor.patch``, where:
-
-* ``major`` - indicates incompatible API changes
-* ``minor`` - indicates functionality added in a backwards-compatible manner
-* ``patch`` - indicates backwards-compatible bug fixes 
-
-## Creating a Release
-
-To create a new release from the ``main`` branch:
-
-1. Update the release notes in ``CHANGES.md``.
-
-   Write a high-level summary of the features and
-   improvements. Include the summary in ``CHANGES.md`` and also in the
-   Release comments.
-
-   Include the log of all PR's included beyond the previous release. 
-
-2. Create a new release on the GitHub Releases page.
-
-3. Tag the release with name beginning with ``v``', e.g. ``v2.3.0``.
+Imath follows the same policy and release process at OpenEXR. See the
+OpenEXR
+[CONTRIBUTING.md](https://github.com/AcademySoftwareFoundation/openexr/CONTRIBUTING.md) for the details.