API version number policy

[John W. Eaton]

On 18-Mar-2009, Rafael Laboissiere wrote:

| Is there a set of well defined criteria for bumping the API version
| number in Octave (api-v*)?  Is this documented somewhere ?
| 
| I am asking because I am currently reviewing the long standing requests
| and bug reports for having properly SONAME'd Octave libraries [1] [2], as
| well as a recently discussion in debian-policy about preventing packages
| to provide shared libraries outside /usr/lib/ [3].
| 
| Before trying to see whether I can propose a patch for this, I would like
| to understand what is behind the api-v* number change.
| 
| [1] http://bugs.debian.org/367165
| [2] http://bugs.debian.org/510579
| [3] http://lists.debian.org/debian-policy/2009/03/msg00147.html

I change it at pretty much every snapshot because I think there are
usually changes that would break compatibility with previous versions
of Octave.  I do this because it is a lot easier than looking
carefully at the sometimes large diffs between snapshots and trying to
decide whether any of the many changes is something that would cause
trouble for someone somewhere if they were to try to use the newer
libraries with an older .oct file compiled and linked with a previous
version of Octave.

We leave it alone for the stable releases.  They are supposed to be
stable, and we are supposed to examine each patch as it is applied to
the stable release series and decide whether it will break
compatibility with previous versions, and if so, not apply the patch
(or find an alternate fix for the problem).

jwe