ABI vs API
==========

Currently ClanLib developers care about ABI and API compatibilty in
the stable releases only, in the development version ABI and API
compatibilty is broken constantly. This leads to a quite bad
situation, stable ClanLib releases tend to be extremly old and
basically useless for developing stuff and development versions break
API every second week, making it almost impossible to keep up and let
users run quite frequently into situation where either their ClanLib
is to old or to new to compile some software.

Proposed Solution
=================

Having a embedable Mini-ClanLib might be one solution, however that
still requires to developers to constantly update their local ClanLib
and will make develpment still a pain, only a bit less painfull.

Another solution might be to first of all get rid of the ABI
compability in the stable releases, this is neither needed for Windows
nor for Linux it only ensures that the .so version stays small, but
that is quite unecessary, beside from that distributors could simply
link everything statically, so there are enough workarounds for ABI
breaking. Stable releases should only care about API, since that is
really the only one that matters much.

The switch over to API only compability should make it much easier to
release stable ClanLibs more often and ensure that fixes and
enhancements can be done in the stable branch. This in turn should
make the stable branch actually usefull for development and for
releasing stuff.

Development branch on the other side should of course not ensure API
compabity. However breaking the API should also be an issue that is
well planed beforehand and not just done ad hock for fun (hint: moving
GUI translations into the 'user' space was NOT a good idea). Functions
that get renamed or removed should be marked as deprecated first and
only get really removed after a grace period. GCC provides a
deprecated attribute for that:

          extern int old_var __attribute__ ((deprecated));
         int old_fn () __attribute__ ((deprecated));

Which could be used like:

#ifndef WIN32
#  define CL_DEPRECATED __attribute__ ((deprecated))
#else
#  define CL_DEPRECATED 
#endif

README.upgrade is a good start documenting changes, but in general it
would be better if there wouldn't as much incompatible changes in the
first place.


# EOF #