[ANNOUNCE] Policy change regarding API and ABI stability

classic Classic list List threaded Threaded
1 message Options
Jan Holesovsky Jan Holesovsky
Reply | Threaded
Open this post in threaded view

[ANNOUNCE] Policy change regarding API and ABI stability


As you might have seen in the ESC minutes, we were thoroughly discussing
how to call the next version, and what to do regarding our API / ABI
policy.  In the end, we came to the following conclusion:

The next version (so far called 3.7) will become 4.0.  With this
version, our approach to API and ABI stability changes - from now on,
changes will be possible on case-by-case basis between versions, as long
as the following rules apply:

* best effort to _not_ to break API / ABI, ie. think twice before you
  attempt to change anything interfacing the outside world in an
  incompatible way

* only small / local incompatible changes where necessary are possible
  (to minimize impact on the outside world, mainly on the extensions

* incompatible changes must be documented in the wiki immediately when
  introduced (dedicated page will be set up) and announced on the
  development mailing list with "[API]" in the mail subject

* the changes are veto-able by ESC case-by-case ('forced' revert)

* larger incompatible changes are possible as long as a smooth
  transition path is provided (with appropriate deprecation first, like
  warnings when used via the SDK, and removal later, eg. in LibreOffice

This explicitly means:

* there might be API / ABI changes in 4.0, but we will do our best to
  minimize them (or their impact) to bare minimum, or even defer them
  to 4.x

* there might be subsequent API / ABI changes in 4.1, 4.2, etc.

I hope I did not forget anything substantial.  Additions / improvements
of the policy of course appreciated :-)

There might be follow-up questions, like "is my change XYZ big or
small", "when am I actually supposed to do my big change XYZ, if at
all?", etc. - I believe the best approach is to present the exact change
first on the ML, discuss it there, and then decide together (on the ML
or via ESC) on the concrete plan.

And of course - if you notice that somebody did an incompatible change
and did not announce it properly (as outlined above), bring it to the ML
as soon as you notice that, to check if it was deliberate or not.

All the best,

LibreOffice mailing list
[hidden email]