Hi Thorsten et al.
sorry for stepping in that late, was quite busy with other things
recently. (And, partly, didn't know whether I *really* want to join this
potentially big and ugly discussion :)
Anyway, thanks for bringing up the topic. I can't but agree with you
(and obviously with Jürgen) that the absoluteness of the "just don't
touch published API" might not make sense anymore. The topic pops up
again and again, so I'd say: let's get the party started ...
> Issue reopened - then please let's discuss this other solution,
> preferrably in the issue.
(personally, I think the mailing list is the better place)
>> Anyway the mechanism should be handled carefully.
>>
>> Don't misunderstand me i am not against API changes in general. I would
>> really love to see some steps in the right direction but not simply by
>> introducing a whitelist without a detailed definition what can be
>> changed. And of course i would keep the current mechanism to explicitly
>> change the reference rdb.
>>
> Understood - but I'm not happy with mixing this technical question
> with the general problem of policy (either way, you would surely
> watch commits to the whatever-it-is mechanism and object changes
> that violate the to-be-defined policy).
In this case, I agree to Jürgen. You problem, which you tried to address
with the patch, is, IIRC, an enum value which was never used and never
implemented (and perhaps even defined in a senseless way?), thus one can
reasonably argue that changing it does no bad at all.
For this, as we learned from Jürgen (I didn't know this before), it's
allowed to change the reference rdb, so the regcompare won't fail.
Comparing your approach - opening a wide portal for all kind of
potentially "wrong" changes - with that one - changing the reference -,
the latter sounds ... less prone to misuse to me. Yes, the latter can be
misused, too, but since changing a reference RDB is a greater hurdle
than just adding a line to a whitelist, chances are better that people
think about what they're doing.
So, for your concrete problem, I suggest you in fact commit a new
version of the rdb file.
Now, away from the concrete problem to the general policy ...
> Definitely. I guess there are (at least) the following cases:
> 1. unused API, or API that crashed OOo, or that was simply ignored
> when calling the OOo implementation
> 2. syntactic changes, e.g. renaming, that will only cause
> recompilation to break, but no existing client (maybe only for a
> defined subset of frequently used implementation languages)
> 3. removal/renaming of seldomly used, or long-time deprecated API
> 4. removal/renaming of often used API
>
> I'd say that 1. and 2. could be unanimously agreed upon, 3. needs
> some careful consideration, e.g. publicly on this list, and a
> migration path, and 4. should maybe just be left alone. ;-)
One question which you implicitly answer for yourself, and which I think
large parts of the whole discussion could boil down to, is the following:
Does our API describe implementations in OpenOffice.org, or is it
describe a generic API which can be implemented in other contexts as well?
(Of course, in reality this question would need to be answered for every
concrete piece of API, but let's save this for the moment.)
The beholders of the holy grail would probably say: the latter. You
implicitly state the first, since you claim that API which is not
used/implemented in OOo can be safely changed.
Which is what I would agree to. That is, I strongly and strictly believe
that our API (now: parts thereof) describes a concrete implementation in
OpenOffice.org, and when the implementation evolves, the API should be
allowed to evolve, too.
As an example, consider services such as css.document.OfficeDocument.
With nearly every new OpenOffice version, there are new interfaces which
are implemented by our document implementations, but which are added to
the service description as "optional", just to not break compatibility.
Which is nonsense: If your client code lives in an OOo 3.0 context, and
works on a document, then it can safely assume the new-in-3.0 interfaces
are present. On the other hand, if (against all probability) there is
client code which implements the OfficeDocument service itself (and
which was really functional in 2.x, despite all the implicit assumptions
made in OOo's implementation, which are far from being documented
anywhere), then this code will most certainly not work in an OOo 3.0, if
it doesn't implement the new-in-3.0 interfaces - simply because those
now became a requirement imposed by OOo's implementation of the
application framework.
So, this is what I think should be the first question before changing
any API: Does it describe an implementation? If yes, the door is open
for changing it, if no, the door is strictly closed.
A rule such as this would save most, though not all, of my grieves with
the "published" paradigm. Lots of my API could be cleaned up then ...
Besides this, there should be some more rules.
As you say in your third item, a policy for deprecated API is missing.
The complete css.data module is deprecated, as is much of the API in
several other modules - I really would like to get rid of those. (Though
this is a minor issue - simply removing all documentation from
deprecated API except the deprecation/successor statement works fine for
me.)
Then, the relaxation of the "published" meaning to a "client code works
again if recompiled" would be tremendously helpful. Heck, why am I not
allowed to add new methods/attributes to an interface? If this interface
really describes an implementation in OOo (ah, the same topic again
...), then I want it to evolve as the implementation evolves and
provides more features.
Sure, we do not need all of the above if we stick to creating XFoo2 and
XFoo3 and XFoo4 and such over time. But this does not really scale, e.g.
because we would also need to introduce XBar2 and XBar3 and XBar4 for
many of the XBars which somehow interact with XFoo.
So, this is not an option if we consider the *usability* of the API.
Yes, API can have a good or bad user experience as well. Finally, this
is why "new-style services" and multiple inheritance interfaces and the
like where introduced. Time to consequently advance on this way.
Play, enough grumping. A concrete suggestion: The two classes
"published" ("can never ever be changed in any way") and "unpublished"
("can change in any way you can imagine, plus a few more") are not
sufficient.
We need something in-between: "Can change in a way that all your client
code using this API still works if you simply re-compile it".
For the next release in reach (3.1), we examine the existing published
API, and look which parts of it we can downgrade to the new class.
And, well, the "we change the API incompatibly if the old version was
mere nonsense"-case should still be possible. This would catch your
concrete case (and more, if you look into the CVS history of the
reference RDB.) But that'd be a careful case-by-case decision, as it is
today.
'nuf said.
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]
