FYI I've now validated those 3 rules by moving out the deprecated methods from ComponentManager into legacy modules (http://jira.xwiki.org/jira/browse/XCOMMONS-150) If you wish to see what's involved: * https://github.com/xwiki/xwiki-commons/tree/master/xwiki-commons-core/xwiki-... * https://github.com/xwiki/xwiki-enterprise/blob/master/xwiki-enterprise-web/p... If we agree with those 3 rules we're ready for the Deprecation day :) Please vote. Thanks -Vincent On Apr 12, 2012, at 2:15 PM, Vincent Massol wrote:
On Apr 12, 2012, at 9:57 AM, Vincent Massol wrote:
Hi devs,
In preparation of our Deprecation Day and continuing our vote on the Deprecation strategy I'd like to propose several rules we need to clarify since we need them and I'd like to finish documenting our full deprecation strategy.
Rule 1: Where are Legacy modules located? ===================================
* Proposal: - Each Git repository needing legacy modules provides a *-legacy module for holding legacy modules. For example: -- For Commons, xwiki-commons-core/xwiki-commons-legacy/ -- For Platform, xwiki-platform-core/xwiki-platform-legacy/ -- For Rendering, xwiki-rendering-legacy/
* Explanation: - It's better to locate them in a specific module (*-legacy) than inside their own module (for ex in xwiki-commons-core/xwiki-commons-component/xwiki-commons-component-legacy/) because legacy modules are something we don't want to see as much as possible since we're must not use them in our code, thus it's logical to park them all together somewhere.
* Notes: - This is our current rule but it's never been explicitly defined
Rule 2: What do Legacy modules contain? =================================
* Proposal: - Each Legacy module should replace the non-legacy module it corresponds to. This means that the user must have only 1 JAR for a given module: either its legacy version or it's non-legacy version but should never have both.
* Explanation: - We need consistency. Right now we have oldcore which acts like this but others don't and it's complex to explain to users that for some they have to swap them and for others they have to keep both side by side - In the very close future, we'll use a lot of Aspects in modules others than legacy-oldcore, and thus we'll need to apply this strategy anyway.
* Notes: - Currently, only oldcore acts like this. - The consequence is that we'll have one legacy module per non legacy modules. Right now we sometimes have one legacy module for several non legacy modules which we'll need to fix
Here's my +1 to both.
We also need some way to know that the move of some deprecated API to legacy works. So I think we need Rule 3.
Rule 3: Ensure that the moved out code works ====================================
* Proposal: - Add a unit test in the legacy module to prove that the moved code still works
* Notes: - Usually this simply means moving the existing unit tests to the legacy module too or duplicating it and use the deprecated classes in the legacy version
Here's my +1
Thanks -Vincent
Thanks -Vincent