[Qt-creator] Dev: Proposed public API/binary compatibility policy

[Nicolas Arnaud-Cormos]

On 03/07/2013 09:57, Ziller Eike wrote:
>
> On 03.07.2013, at 09:11, Nicolas Arnaud-Cormos <nicolas.arnaud-cormos at kdab.com> wrote:
>
>> Hi Eike,
>> On 02/07/2013 11:55, Ziller Eike wrote:
>>> Hi,
>>>
>>> this is the proposed API / binary compatibility policy for 3.0 onward:
>>>
>>> * Source and binary compatibility within a minor release series
>>>     * no "unnecessary" public API changes after the Beta release,
>>>       changes must be communicated (e.g. note on the mailing list with the change)
>>>     * public API fixed starting with the RC release
>>>     * plugins written against the final (.0) release can also be loaded in following patch releases
>>>       i.e. patch releases have a compatVersion tag for .0 in the plugin spec
>>
>> Looks good indeed, but you only address binary compatibility between
>> patch releases.
>> What about minor releases? I suppose there's no binary compatibility for
>> minor releases (ie a plugin written for 3.0 won't work for 3.1), but I
>> prefer to ask just to be clear.
>
> Yes. I can add a sentence to make that clear when I update
> http://doc.qt.digia.com/qtcreator-extending/coding-style.html#binary-and-source-compatibility

Actually, there's one:
"We do not currently guarantee API nor ABI (application binary 
interface) compatibility between major releases and minor releases."

Good enough.

>>> Example:
>>>
>>> The public API of the Qt Creator 3.0 series will be fixed starting from 3.0 RC, which has internal version
>>> number 2.8.8x, compatVersion 2.8.8x (a). The final 3.0.0 release is binary compatible to the 3.0 RC,
>>> but has compatVersion 3.0.0 (b). So even though the 3.0.0 release is factually
>>> binary compatible with 3.0 RC, it can only load plugins that were written against 3.0.0.
>>> A patch release 3.0.1 is binary compatible to 3.0.0, and has compatVersion 3.0.0 (c), so plugins that were
>>> written against 3.0.0 load in 3.0.1. Plugins that are written against 3.0.1 can decide themselves if
>>> they require 3.0.1 (d), or work with 3.0.0 (e) (by setting the version tag of the dependency accordingly).
>>
>> I'm not sure I'm following you here. Plugins written against 3.0.1 can
>> decide to depend on Core 3.0.1 only. In this case, those plugins won't
>> have a compatVersion of 3.0.0 (like in (c)), but 3.0.1, right?
>> So the dependency really depends on the compatVersion, not the version.
>
> The plugins specify a single version that they need of another plugin. That other plugin specifies to which versions of itself it is compatible, with the compatVersion attribute. The compatVersion attribute of a plugin Foo has *nothing* to do with the Qt Creator version (there is no such thing as a "Qt Creator" version when we are talking about plugins / the plugin manager).
>
> (a) Qt Creator 3.0.0 has plugin "Core" with:
> <plugin name="Core" version="3.0.0" compatVersion="3.0.0">
> ===> this version of plugin "Core" is version 3.0.0 and it is binary compatible to plugin "Core" version 3.0.0
>
> (b) Qt Creator 3.0.1 has plugin "Core" with:
> <plugin name="Core" version="3.0.1" compatVersion="3.0.0">
> ===> this version of plugin "Core" is version 3.0.1 and it is binary compatible to plugin "Core" version 3.0.0
>
> <plugin name="Foo" version="1.1.2" compatVersion="1.1.0">
> ….. <dependency name="Core" version="3.0.0"/>
> ===> this version of plugin "Foo" is version 1.1.2 and it is binary compatible to plugin "Foo" version 1.1.0
> ===> it has a dependency to plugin "Core" requiring a version that is compatible to "Core" version 3.0.0
> ===> that means that it loads in (a) Qt Creator 3.0.0 and (b) Qt Creator 3.0.1
>
> <plugin name="Bar" version="2.1.0" compatVersion="1.0.0">
> ….. <dependency name="Core" version="3.0.1"/>
> ===> this version of plugin "Bar" is version 2.1.0 and it is binary compatible to plugin "Bar" version 1.0.0
> ===> it has a dependency to plugin "Core" requiring a version that is compatible to "Core" version 3.0.1
> ===> that means that it loads in (b) Qt Creator 3.0.1 but *not* in (a) Qt Creator 3.0.0
>
>
> See also http://doc-snapshot.qt-project.org/qtcreator-extending/plugin-specifications.html#dependencies
> (If you think that the documentation in that link is somehow unclear and have ideas for improvements, I'm happy to discuss patches
> to doc/api/plugin-specifications.qdoc  :) )

I totally mixed up the compatVersion attribute, sorry about that (so 
used to see the same version everywhere).
Documentation is good, no need to change it.

I should have started by reading the doc...

Thanks,
Nicolas

-- 
Join us in October at Qt Developer Days 2013! - https://devdays.kdab.com

Nicolas Arnaud-Cormos | nicolas.arnaud-cormos at kdab.com | Senior Software 
Engineer
KDAB (France) S.A.S., a KDAB Group company
Tel. France +33 (0)4 90 84 08 53, Sweden (HQ) +46-563-540090
KDAB - Qt Experts - Platform-independent software solutions