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

Mon Jul 8 10:28:57 CEST 2013

On 05.07.2013, at 20:50, Tobias Hunger <tobias.hunger at gmail.com> wrote:

> Hello everybody!
> 
> Could we please define more clearly what is applicable to those
> promises of source and binary compatibility?
> 
> I would suggest that experimental plugins are not effected by them.

Fine with me. Though consider that binary & source compatibility is only related to *public* API in plugins, i.e. *exported* API (that is not in internal namespace).
So even experimental plugins would only be affected at all by this if they export API to the outside, which I don't think any does atm.

> Those plugins are
> * expected to change rapidly
> * already communicated to be "unstable" for our users
> * untested to an extend that I feel uncomfortable to promise that
> necessary fixes will not effect binary compatibility.
> 
> We also have parts in Creator that depend a lot on external projects
> (be it qbs, clang, lldb or whatever) that are evolving (some of them
> rapidly). Most of these will be in experimental plugins, but some code
> might end up as extensions to already stable plugins. Should we agree
> on some form of documentation to warn people away from those areas?

Most of the time I'd expect plugins that depend on "external" libraries to use these purely for internal purposes.
Binary compatibility concerns only appear if types of these libraries are exposed through *public* API of these plugins.
I suppose it would be good to avoid these, and when it is done, make it a very deliberate choice.
Like we do with Qt as an "external" framework ;)

But actually we haven't covered one point yet: The binary compatibility policy should not only cover the Qt Creator plugins, but also the utility libraries that we provide. I think we need to list the ones that are covered explicitly, since not all in src/lib are really "public":

aggregation
cplusplus (exposed throught the model manager et al)
extensionsystem
languageutils
utils

I'm not sure about qmljs, to me it looks like this is used by qmljseditor/-tools/-debugger, so is it to be consider public API for use by others, or not?

Br, Eike

> Best Regards,
> Tobias
> 
> 
> 2013/7/3 Nicolas Arnaud-Cormos <nicolas.arnaud-cormos at kdab.com>:
>> 
>> 
>> 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
>> _______________________________________________
>> 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