Concepts for incompatible API changes and an API deprecation process

Concept for incompatible API changes

Background

Today we have over 4280 IDL types, many types defining how to define or transport data, how to access certain data, information via certain interfaces. Many types defining Service Provider Interfaces that allows to extend the feature set of OpenOffice with completely new features or with further implementation of the same category (eg. filter, calc add-ins, etc). When the design of the office API started the goal was to design one API for all the different use cases and make use of the UNO technology to use this one API from different programming languages. A very high goal which sounds perfect from the beginning but the reality is that users of the API have different skill levels and different requirements to an API. The design focused mainly on internal usage to drive the modularization of the office core and provide a better flexibility. Basic means macro developers should use the same API but a macro programmer has a different abstraction level and prefer a more highlevel API. The whole API is very fine grained, allows many modification on a fine grained detail level and make use of object oriented concepts. So far so good but a further goal was to keep the API compatible which a nice goal but in the reality hard to achieve. Especially when you take into account that many API's were designed without really using them. Not a very good approach to create good API's that ideally evolve over time and where feedback is integrated to improve them. The problem of changing API's is not the office core but existing macros in documents or extensions. The problem increased over years and new interface where introduced where normally an existing one would have been changed. New UNO concepts were introduced to make API's much more intuitive and easier to use. Ideally existing API's would have been changed to improve from these very useful changes. We used the new stuff only for new API's. Many design errors remain unchanged in the API and make the whole API not really better over time.

Incompatible changes

Over time we recognized that we have to allow useful incompatible changes to move the project, the product forward and to be able to change things.

Requirements for an incompatible API change:

incompatible changes should be allowed to major releases only
the change must be communicated clearly in advance
a migration path from old to new have to be documented with examples. (additional tooling support is appreciated if possible)

API deprecation process

Sometimes it is also useful and necessary to deprecate API's to be able to remove them over time. This can make sense for cleanup reasons but more often because the supported feature is dropped or removed completely. Or the API as it is today make no longer sense at all.

Requirements for deprecated API's:

API's can be deprecated with every major, minor release.
recommendation is to support a deprecated API for at least one further (minor) version. Means a deprecated API for 3.4 should not be removed in 4.0 when 4.0 is the next major/minor version after 3.4.
deprecated API's can be removed in major release only

This work is licensed under the Apache License version 2.0