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-commons-legacy/xwiki-commons-legacy-component * https://github.com/xwiki/xwiki-enterprise/blob/master/xwiki-enterprise-web/pom.xml 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 >> > _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
