AddInInterface version number based on semantic versioning

Issue #105 resolved
M. Gronle created an issue

With this proposal, I suggest to introduce rules for the version numbering of the AddInInterface.

This version number can be found at the bottom of the document addInInterface.h.

Current situation

The version number is incremented in an unspecified way once a binary-incompatible change (see https://community.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B) is done to any library, that is part of the itom SDK. If itom loads a plugin or designerPlugin, it compares the addInInterface version number of this plugin with the addInInterface number of itom itself. If they are equal, the plugin is loaded, else it is refused.

Proposal

I propose to use the rule of semantic versioning (https://semver.org/) for the interface version number. Hence:

Major.Minor.Patch

  • The patch is incremented, if any kind of bugfixes are done without changing any part of any exported libraries, that are part of the SDK of itom.
  • The minor number has to be incremented, if anything is added in a backward compatible manor to any library of the SDK. Backward compatible means, that the binary compatibility is still given.
  • The major number has to be incremented, if anything is changed, added or removed, that breaks the binary compatibility of the SDK.

If this pattern is introduced, itom can insert a more relaxed scheme for accepting plugin or designer plugin libraries:

  • For any interface <= the current interface number 3.2.0: The old rule holds and the exact, full version number must be equal
  • For an interface number > 3.2.0: itom accepts plugins, implementing the same major number, a minor number that is smaller or equal than the number of itom and any kind of patch number. Example:
itom plugin load accepted
3.1.3 3.1.3 OK
3.1.3 3.1.2, 3.1.4 NO
3.2.0 3.2.4 OK
3.3.1 3.3.0, 3.2.0 OK
3.3.1 3.3.2 OK
3.3.1 3.4.0, 4.0.0 NO

Comments (2)

  1. M. Gronle reporter

    The implementation of a more robust AddInInterface version is not feasible without incrementing to a new major interface number. The reason for this is not only the new version number pattern, but a version check problem with the designer plugins. In the current implementation, plots have their own plot-interface version. However this check is wrongly implemented, such that it will always succeed. The problem comes from the question in which part of library a method is compiled and in the current implementation, the plot-interface version is part of the itomCommonPlot.dll and not of the plot itself. Hence, the check does nothing 😉

    Currently, the addIn interface version is also changed if any binary incompatible changes are made to other libraries, that belong to the SDK (e.g. dataObject, …). However, the plot interface version has to be altered in this case, too. This was not always the case in the past. Additionally, there are plugins that link against plots. Such that changing the plot interface requires changing the addIn Interface number, too.

    If we put all this together, I suggest to use the same addIn interface number for plots and ordinary plugins. I am currently implementing this, however due to the wrong implementation of the plot interface number, we have to add a kind of one-line macro in the designer plugin interface class of every plot. This is the same for ordinary plugins, which have the PLUGIN_ITOM_API macro. This macro internally creates some things which are necessary to properly use the plugin as itom plugin.

    Therefore I will create a macro DESIGNER_PLUGIN_ITOM_API. This has then to be added, like:

    class Itom1DQwtPlotPlugin : public ito::AbstractItomDesignerPlugin
    {
        Q_OBJECT
    #if QT_VERSION >=  QT_VERSION_CHECK(5,0,0)
        Q_PLUGIN_METADATA(IID "org.qt-project.Qt.QDesignerCustomWidgetInterface" )
    #endif
        DESIGNER_PLUGIN_ITOM_API
    

  2. Log in to comment