[sword-devel] How broadly do we define "API"
dmsmith at crosswire.org
Wed Jun 10 11:40:47 MST 2009
Jonathan Marsden wrote:
> Troy A. Griffitts wrote:
>> 1.6.x has been dubbed a non-API-breaking/binary-compat stable branch. If
>> you want to call that a bug-fix branch, great. We are in a phase of
>> development currently which doesn't require a branch. We are fixing
>> bugs, optimizing, and improving filter support, etc. These are all
>> things which will be released in the 1.6.x thread of releases. As soon
>> as we decide we need to commit something that breaks API/binary
>> compatibility, then we'll branch 1.6.x and continue 1.7.x on HEAD.
> OK, that is fine at the library API level, and is good news :)
> At the level of utilities that are used in scripts, and whose command
> line parameters are therefore in some sense an "API" for those who write
> scripts using them, the very recent (post 1.6.0) change to osis2mod that
> adds the -d option *already* broke "osis2mod API compatibility" :)
I don't agree. There is not one possible prior use of osis2mod that the
addition of this flag would cause a breakage. With regard to input
flags, I figure that there are those that have shell scripts that call
osis2mod. Removing flags or changing their meaning should be done with
caution, involving discussion here first.
That said, I agree with Chris that command-line parameter compatibility
of these utilities is not as significant as their usability.
To me the real measure of API compatibility for osis2mod should be does
it create modules that require the same SWORD engine, or does it require
a newer one. It should not be whether the module is identical.
My personal goal is that osis2mod will work with the required engine as
long as possible. For example, osis2mod for 1.5.11 would build modules
that were compatible with 1.5.9. It was possible that the OSIS input
would require some later version.
The current version of osis2mod builds modules that require 1.6.0 SWORD
Currently trunk is the 1.6.x bug-fix area, as others have noted. We are
contemplating a bug fix for osis2mod that will require a bug fix in the
SWORD engine. The change to the SWORD engine will occur first. With that
release osis2mod will require the corresponding SWORD engine or later.
(I think both will be 1.6.1).
> I'd consider that kind of change an enhancement, rather than a bug fix.
I'd consider it a bug fix in the usability of the program ;)
> So even though I thought it was useful, I left it out of the SWORD
> 1.6.0+dfsg-1 packages...
Works for me. Even when osis2mod is part of a distribution, my
recommendation is still to build from current source. If a module is
submitted to CrossWire for inclusion, we will rebuild it using the
latest and greatest.
More information about the sword-devel