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

[Tobias Hunger]

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

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