Hi Thorsten,
thanks for the infos from the ESC. I think we have to discuss and to
define a lot of things here.
Before we start discussing it in more detail, please can we agree to
continue on one mailing list only. I would suggest to continue on the
d...@api.openoffice.org list because it is API related and the correct
list for it.
I would also suggest to summarize all the outcome of the discussion on a
new wiki page in the API section.
I have created the following page
http://wiki.services.openoffice.org/wiki/API/Concepts_API_changes
Display title=Concepts for incompatible API changes and an API
deprecation process
Thanks
Juergen
Thorsten Behrens wrote:
Hi *,
on the last ESC meeting, we had a little brainstorming about if and
how to deprecate OOo API. The 'if' was unanimously agreed upon,
for the 'how' we came up with the following thoughts:
API deprecation
===============
See
http://wiki.services.openoffice.org/w/images/2/2a/Esc-mar-2009-api-deprecation.odp
for the kickoff slides
-- What we need to do --
Decide on preconditions for change:
- API was badly designed (architects/pleads to vote if not
concordant)
Have a list of 'design smells' here, e.g.:
* missing exception specifications
- API is unused
* implemented but unused (can only be easily verified inside OOo
code repo, with some more effort inside extension repo - is
that enough?)
* not implemented (maybe transitively, i.e. listener interfaces,
which are meant for API clients, but don't have code to call
them inside OOo)
- API implementation is too expensive (referring to both effort &
performance) (architects/pleads to vote if not concordant)
What we mean here is e.g. (hypothetical):
* profiling xml import has shown that
css::xml::sax::XEntityResolver is horribly inefficient and
needs a third argument
* after the drawing layer rework, one of the css::drawing
interfaces needs an inordinate amount of code to emulate old
semantics
Decide on constraints:
- how many clients does this API have
* inside OOo code
* (estimated) use outside OOo repo
* (estimated) number of implementers not reading
interface-announce
For the latter two, if (at most) recompile is enough, any number
of implementers won't block change.
For the latter two, if syntactic changes are required, have
architects/pleads majority in favor of change?
- how 'bad' is the API really – if bad enough, change anyway?
Process of Change
- when would change be permitted - every feature release, or only
major releases?
- deprecate API in advance - one or two features releases before
the actual removal. Of course, a replacement needs to be
available then?
- can/should we add technical barriers/support for detecting stale
API usage, i.e. refuse to run such extensions? Should we add
technical means to warn devs when using deprecated API (either
enabled in debug builds, or in a special logging mode of OOo)?
Who decides?
- we've referred to the entity finally deciding as
"architects/pleads" here; please consider that a place holder.
We'd like to hear sensible proposals here also for that
committee, also simply voting on the relevant project mailing
list is conceivable, or just having the respective project lead
decide.
Looking forward to your ideas,
Kay, Frank & Thorsten
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@api.openoffice.org
For additional commands, e-mail: dev-h...@api.openoffice.org
--
Sun Microsystems GmbH Juergen Schmidt
Nagelsweg 55 Technical Lead Programmability
20097 Hamburg, Germany
Registered Office: Sun Microsystems GmbH, Sonnenallee 1, D-85551
Kirchheim-Heimstetten
Commercial register of the Local Court of Munich: HRB 161028
Managing Directors: Thomas Schroeder, Wolfgang Engels, Dr. Roland Boemer
Chairman of the Supervisory Board: Martin Haering
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@openoffice.org
For additional commands, e-mail: dev-h...@openoffice.org
