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

[Jonathan Marsden]

Troy A. Griffitts wrote:

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

My suggestion would be that 1.6 be a transitional release in this
regard, with both the older and newer approaches working, and with an
included README file or NEWS file (or both) notice that the older one is
deprecated and will no longer be supported in 1.7, developers using the
library should transition to the newer interface.  Then in a year or so,
they are forced to do so.  This gives SWORD application developers time
to adjust to the changed API.  (If you really want, and assuming the
library already has a standard way to emit warnings, you could make the
old interface method in 1.6.x emit a warning about it being deprecated,
every time it is used, as a further incentive/reminder to developers.
There is plenty of precedent for this kind of warning, such as in
several changes to the Linux kernel API and to the glibc standard C
library.)

This approach both keeps compatibility with existing application code
*and* adds a feature you clearly feel is important to the 1.6 API,
despite its (IMO) somewhat late and apparently unexpected/unheralded
arrival.  That's "both", which is what you said you'd like :)  Best of
both worlds??

Is this something you are willing to consider?

Jonathan