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...@udk.openoffice.org For additional commands, e-mail: dev-h...@udk.openoffice.org
