[sword-devel] How broadly do we define "API"

[DM Smith]

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

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.

In Him,
    DM