Approach for backward compatibility

[Alfonso Martínez de Lizarrondo]

This is due to the patch in #4973, but it was a long talk that would distract from the real patch.

The patch in #4972 (v2) removes CKEDITOR.loadStylesSet and CKEDITOR.addStylesSet, so when people tries to upgrade they will get an error if they have used them.

I think that most of the people didn't know anything about CKEDITOR.loadStylesSet unless they had to fight with the lack of CKEDITOR.stylesSet ​as I did, but I think that there's lots of people using their own styles with the addStylesSet call. If they don't change the code then it will fail and they have to find out the reason.

So my question is: how do we approach backwards compatibility?

We can leave the code as is and they have to read the release notes to notice the reason of the problem. This can be more complex if they are upgrading for example from 3.0 to 3.3 with hundreds of bugs in the mean time.

We can add bold and red statements in the what's new to make it clearer, but they still have to read the docs.

We can provide also a "compatibility" plugin that it's used just to provide compatibility with older apis. This plugin could define just the old functions as mapping to the new APIs and launch a silent warning in the console (if it exists)

Something along these lines:

CKEDITOR.addStylesSet = function( name, styles ) 
{ 
    if (window.console)
        window.console("The CKEDITOR.addStylesSet function has been deprecated. Please use CKEDITOR.stylesSet.add. Read... for further info");
    CKEDITOR.stylesSet.add(name, styles)
};

This way the upgrade is easier, there's a very little overhead and people can remove the plugin when they know that everything is working OK.

[Frederico Caldeira Knabben]

First of all, we should avoid bringing drastic changes to the API. We should do that only when extremely needed. That's why adding API functions mus tbe a well thought thing. In the exemplified case, we can definitely maintain CKEDITOR.addStylesSet in the code, as it would not bring much extra code with it.

Then, if we see that we're introducing important changes, I liked the "compatibility" plugin idea. We could even use CKEDITOR.revision on it to check which changes to be made.