30 Jan
2009
30 Jan
'09
10:42 a.m.
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#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