[sword-devel] [bt-devel] Compatibility break: Sword 1.6RC1->RC2 API change
eekaikko at mail.student.oulu.fi
Thu Apr 23 23:31:40 MST 2009
Quoting "Troy A. Griffitts" <scribe at crosswire.org>:
> Thanks for the support and I understand the criticisms. Let me just
> say that the one difference here is that we are talking about a 1.6.x
> BRANCH in which NO API changes can be made once it happens. It is this
> point that is weighing heavier on the decision to make the change right
> now before the branch. Honestly, I'd rather have the interface where I
> want it right now over stability (obviously I'd like both). Once 1.6.x
> is branched, I have no problems releasing monthly if we feel the need,
> but it will likely be another year before we branch again and get
> interface changes out in the wild. Hope this helps explain the
It is understandable. We also have to remember that the situation here
is quite rare and Troy (or others) didn't have much experience on
releasing such an important milestone as 1.6 is. We have to learn from
this and not repeat some mistakes.
A library is much more critical than an application. We can release
apps just like that, changing whatever, and it may temporarily affect
few users. But if there are 5 frontends using a library, a change may
affect 5*n developers and 5*m end users. If the app architecture is
rigid, one small API change may ruin the whole thing.
It is usual practice to mark some API features deprecated. It could
have been done here, too. Better yet, why not let the setter function
be (at the moment, put it back). It was there only for a short moment,
but in this situation it allowed frontend developers continue with old
architecture. If it's important to make sure that the developers
understand what they are doing, why not rename the setter as
It still changes the API but doesn't force to subclass. The virtual
method and this setter can live peacefully together: the default
implementation of the checker would return either the value set by
this setter or false.
Jon is correct, maybe this should have been called beta instead of RC.
It's very difficult to make these decisions. Usually I would wait a
little longer and would release one more pre-alpha for BibleTime but
Martin just tags beta or RC :) But anyways, calling a library an RC
should mean there are no more API changes unless they fix critical
bugs. This one wasn't critical, not even a bug.
And still one little issue: the version number was still 22.214.171.124,
for both RC1 and RC2. It should have been pumped up to 100 (there's
nothing wrong in using 100 as a version number!).
The bright side of this situation is, at least in my opinion, that the
Sword library is growing in importance. Our practices and skills
should just grow along with it.
More information about the sword-devel