[xwiki-devs] [Proposal] XWiki javascript APIs deprecation/compatibility strategy

Hello devs, We need a deprecation/compatibility strategy for our javascript APIs, as we do have one for Java (see http://lists.xwiki.org/pipermail/devs/2008-February/005067.html and http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HBackwar…). I propose we embrace the same idea: keep backward compatibility separate from actual code, creating a file "compatibility.js". Since it's a compatibility layer, our releases should work properly without including this file. We should discuss if we want include it by default or not. As we are doing with the velocity uberspector, I propose we also log a warning for every call to a deprecated JS API to help our users update their code. For this I propose we have a depreciate method in compatibility.js with the following signature : function depreciate(scope, method, since, useInstead); That method would weave the warning log before the actual call to the method. A typicall deprecation would then look like this, in compatibility.js : window.checkAdvancedContent = XWiki.isAdvancedContent // keep compatbility depreciate(window, checkAdvancedContent, "1.8M2", "XWiki.isAdvancedContent"); // but log every call to checkAdvancedContent As for Java APIs, I propose we keep compatibility at least 2 full releases after the current version is released as final before we allow ourselves to remove deprecated methods. As for what should go through this deprecation cycle, I would say everything that is now in xwiki.js. There are methods we publicly advertise, for example updateName (http://www.theserverside.com/tt/articles/article.tss?l=XWiki). For our other files (usersandgroups.js, ajaxSuggest.js, fullscreenEdit.js, etc.) I think we can refactor them without going through a deprecation cycle. In any case, for the future we should be more careful and expose as APIs only what we plan to support. My +1 for this strategy WDYT ? Jerome