API for next stable release of base library

[Richard Frith-Macdonald]

I'd like us to be able to make a stable release (1.14.0) of the base  
library early next year (before FOSDEM) and want to make sure that we  
get any reorganisation needed to keep the base library APIs stable  
for a long time done by then.

Anything we want to deprecate/remove needs to be marked as deprecated  
by that release, so we can remove it in the next-but one release  
after it.

Any reorganisation and additions of APIs replacing deprecated APIs  
needs to be in place by then, so that people can move from using  
deprecated to undeprecated APIs.

Changes of instance variable layouts need to be done by then, so that  
code built against that release will work with later versions of the  
library (at least until the 1.16.0 release, and preferably longer).

The sort of cleanups I'm thinking of are ...

1. Make certain that no private APIs are publicly exposed, so there  
is absolutely no chance of people using internal APIs accidentally  
and so that they would have to make a major effort to use them anyway  
(some people think they can manage changes in private functionality,  
and attempt to use it as a shortcut for writing portable/reliable code).

2. Audit instance variables in classes to make sure that privagte  
ivar's are all marked as such, and make sure that there is a way to  
add extra ivars to each class without changing the overall size of  
the ivars and/or the layout of the public ivars.

3. Clean up public extension APIs ...
probably deprecate any odd bits and pieces such as optimisation hacks  
and convenience methods which only save a few lines of code ... to  
keep the API as a whole slim and easily understood.
perhaps group together associated functions into class-based APIs,  
for a cleaner, more organised interface and so that users can extend/ 
override methods easily and generally stay within the object-oriented  
programming idiom.
perhaps move the additions library GC classes into a separate library.
perhaps look at naming conventions and orthogonality of methods in  
the other additions library classes.

4. Make sure that anything which can be declared 'static' *is*  
declared' static', to avoid clashes at link time.   Do an audit of  
non-static symbols to help with this.

Any ideas about how to do this sort of audit in practice, and  
minimise the work involved in doing a similar audit for later releases?

My best idea at the moment is that using 'nm -g --defined-only' to  
list symbols will give us a base view of the exposed API, and if we  
keep a dump of that output we can use standard tools like sort and  
uniq in a shell script to let us know about changes ... so we can  
tell if we have accidentally added,changed, or deleted something.

What API changes ought to be made?
What base library classes still contain extensions which should be  
moved to the additions library?
Which classes need ivar changes (to allow for later extension without  
having to change the ivar layout again).