30 Jan
2009
30 Jan
'09
12:08 p.m.
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#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
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs