Hi Ariel, > oh no, please, do not do this: from an API-client point of view, this > may be confusing... although there are already some Something2 / > XSomething2 in the API :-(
which is ugly, as we seem to agree (though you cannot always avoid it) > There is at least some thing in which you developers should get to some > consensus : means "unpublished" some kind of warning like > "DO-NOT-USE-IT, IT'S NOT SAFE!" , or "this may be improved in the future > by *adding* extra functionality, but you can begin to use it safely in > your code"? Well ... IMO there's actually 3 different states of an API, at least: 1. stable: Not to be changed anymore, you can safely use it in any way you like 2. mature, but potentially instable: Though we're not completely sure the API already captures all facets of the problem, changes are relatively unlikely, and if they happen, they will probably be compatible. Source-code compatible, at least, so in the worst case, you probably only need to recompile your code. In seldom cases, It might be you need to do adjustments to your code, but they should be minor. 3. immature: We *know* the API is going to change incompatibly. It is not finished, but we decided to put it in so some people can already benefit from it. (1) is captured by today's "published". (2) and (3) are captured by today's "unpublished". The smart tag API in 2.2 is a good example for (3). The already mentioned OfficeDatabaseDocument, however, fits into (2) (or we need an extra category): Actually, the OfficeDatabaseDocument describes an *implementation*, which evolves as OOo evolves. For instance, with macros in database documents, there are 2 additional interfaces to be supported by an OfficeDatabaseDocument. In the future, when we add more features, there will be even more interfaces. Declaring the OfficeDatabaseDocument as "published" (and putting it into category (1) this way) would prevent me from adding those interfaces, except as "optional", which would be a plain lie. So, the OfficeDatabaseDocument is kept unpublished - which leaves the API user with the impression it can change dramatically in the future, which simply is not the case. So, for such problems, we're down to: (a) Don't publish it - this will make the user think it's unreliable. (b) Publish it, and add later interfaces as "optional" - which will make the user think those new interfaces are unreliable. In both cases, the user's impression is wrong. Having said all this ... this discussion has been there several times already, usually in [EMAIL PROTECTED] Unfortunately, I could not convince the relevant people so far that IMO we need a distinction between (2) and (3). Ciao Frank -- - Frank Schönheit, Software Engineer [EMAIL PROTECTED] - - Sun Microsystems http://www.sun.com/staroffice - - OpenOffice.org Base http://dba.openoffice.org - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
