22 May
2012
22 May
'12
11:30 a.m.
On Tue, May 22, 2012 at 9:08 AM, Thomas Mortagne
<thomas.mortagne(a)xwiki.com> wrote:
On Mon, May 21, 2012 at 7:12 PM, Jerome Velociter
<jerome(a)winesquare.net> wrote:
Besides the WYSIWYG, there is the REST module that also has (wrongly)
only public code.
For other modules it looks better, though I think there are quite some
interfaces that are offered as public for the sheer fact they are
interfaces ; which is a mistake IMO.
Also, there is the case of the DocumentAccessBridge, which by essence
is meant to grow, thus be broken (but maybe it is "complete" now,
though if you think about it, our present rule would not have permit
us to elaborate it in the time-frame we did - which is a couple of
years)
Jerome
Hi devs,
Following a thread on github, here's a mail to start a discussion
about the way we determine what is API or not.
Our current rule is :
1) "Non user-public code must be located in an internal package just
after the module name." c.f. [1] (implied that what is not in internal
is public)
2) What is public has to go through the deprecation strategy described at [2]).
I think the rule is good but there is a problem in its enforcement
right now, mainly because :
* There is some legacy code where 1) does not make much sense because
it "arrived too late at the party" (for example in oldcore)
* There is some "new code" where some classes/interfaces hasn't been
made internal when they likely should have been. For example I've been
playing around with the WYSIWYG recently and in the client module,
there are *only* user-public classes [3]. I'm sure we can find a lot
of examples of such practice and I'm OK to work and list some if
needed.
The problem I see coming is that the cost of refactoring will increase
for a lot of modules/classes/etc., while at the same time those
modules should not have been API to begin with, and are probably not
even being used as such by anybody. The risk is our progress being
bogged down for no good reason.
So what can we do to enforce a solid backward-compatibility policy for
API code, while keeping flexibility in XWiki internals ?
We could :
A) Not do anything :) Maybe it's just me that sees this as a potential problem.
B) Do the work to move everything that ought to be in an internal
package to an internal package. But I don't believe we're reading to
make that effort, so that's not going to happen IMHO
C) Do the work to move what ought to be in an internal package "on the
fly", when refactoring code. That would be on a case-by-case case,
probably requiring a mail to announce it ; or more coercive, a VOTE.
C) We change the rule. We could decide that instead of having
everything be an API and enforce the "internal" status in a special
package, we take it the other way around and Day everything is
internal, and APIs needs to be in a special package (or be annotated
with a special annotation). This could also be the opportunity to
introduce another rule that says that such APIs should be referenced
in their own module documentation on extensions.xwiki.org.
What do you think ?
Big -1 to force putting public APIs in a specific useless package.
The main issue is mostly with oldcore which is supposed to be
refactored at some point peace by peace anyway so that's not a big
issue IMO. It's just another argument to get rid of it ASAP.
For "new" modules, if some code is is public while it should not then
it should be fixed ASAP and indicated in the release note (since it's
a breakage even if it should never have existed in the first place) or
made @Deprecated if it's too old and jugged probably already used to
be removed like that, in both cases it would require a VOTE IMO. Note
sure if that's B or C.
The status of new code is not as bad as you think IMO and I don't see
the point in changing a good rule because it's not applicable to old
code that's supposed to be replaced anyway at some point. Whatever the
new rule you will never be able to apply it to oldcore anyway... For
example C does not work since we have a lot of things we do want
public for java code which are not in the "api" package and we are not
going to deprecated and move them there since it does not worth the
effort.
--
Jérôme Velociter
Winesquare
http://www.winesquare.net/
Jerome.
[1] http://dev.xwiki.org/xwiki/bin/view/Community/JavaCodeStyle#HPackagenames
[2]
http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HBackwar…)
[3]
https://github.com/xwiki/xwiki-platform/tree/master/xwiki-platform-core/xwi…
--
Jérôme Velociter
Winesquare
http://www.winesquare.net/
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
--
Thomas Mortagne
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs