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

[Ziller Eike]

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

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

Br, Eike

> 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
> _______________________________________________
> Qt-creator mailing list
> Qt-creator at qt-project.org
> http://lists.qt-project.org/mailman/listinfo/qt-creator

-- 
Eike Ziller, Senior Software Engineer - Digia, Qt
 
Digia Germany GmbH, Rudower Chaussee 13, D-12489 Berlin
Geschäftsführer: Mika Pälsi, Juha Varelius, Anja Wasenius
Sitz der Gesellschaft: Berlin, Registergericht: Amtsgericht Charlottenburg, HRB 144331 B