[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#HBackward...). 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
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#HBackward...).
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 devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
Sounds good. What would the depreciate method actually do? * log on the server side using ajax * log on the client side using browser's console (firebug on ff) +1 for the strategy. Thanks, Marius 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#HBackward...).
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 devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
Marius Dumitru Florea wrote:
Sounds good. What would the depreciate method actually do?
* log on the server side using ajax * log on the client side using browser's console (firebug on ff)
I asked myself the same question. If we go for the server side we need an API + a velocity service... I personally would go for firebug only with console.warn Jerome.
+1 for the strategy.
Thanks, Marius
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#HBackward...).
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 devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs
participants (2)
-
Jerome Velociter -
Marius Dumitru Florea