[xwiki-devs] [Discussion] Should we re-think the way we determine what is user-public code ?

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 ? 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/