id	summary	reporter	owner	description	type	status	priority	milestone	component	version	resolution	keywords	cc
5025	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 [http://alfonsoml.blogspot.com/2009/12/class-selector-in-easyupload.html 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."	Task	new	Normal		General			Discussion