[bt-devel] Compatibility break: Sword 1.6RC1->RC2 API change

[Eeli Kaikkonen]

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
> decision.

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  
"iSwearToMyHeadThatIHaveShownAWarningToUserAndUnderstandThatPeoplesLifesMayDependOnIt(bool)"
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 1.5.11.99,  
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.

--Eeli Kaikkonen