Forgot to say: if we agree, I'll add this to our dev practices on http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices
Jerome. (but maybe next year, though ;)) Jerome Velociter wrote: > 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#HBackwardCompatibility). > > 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 > _______________________________________________ > devs mailing list > [email protected] > http://lists.xwiki.org/mailman/listinfo/devs _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
