On 03/29/2012 04:06 AM, Vincent Massol wrote: > Transforming this thread in a brainstorming since we couldn't get to an > agreement quickly. Once it's settled I'll launch a second vote. > > See below. > > On Mar 29, 2012, at 8:20 AM, Vincent Massol wrote: > >> Hi Caleb, >> >> On Mar 28, 2012, at 11:28 PM, Caleb James DeLisle wrote: >> >>> >>> >>> On 03/28/2012 02:03 PM, Vincent Massol wrote: >>>> >>>> On Mar 28, 2012, at 7:10 PM, Denis Gervalle wrote: >>>> >>>>> On Wed, Mar 28, 2012 at 12:27, Vincent Massol <[email protected]> wrote: >>>>> >>>>>> Hi devs, >>>>>> >>>>>> I'd like to change our deprecation strategy. Here's what we are currently >>>>>> supposed to use (we voted it a long time ago): >>>>>> >>>>>> http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HDeprecation26LegacyStrategy >>>>>> >>>>>> " >>>>>> In addition our rule is to keep @deprecated methods/classes for 2 final >>>>>> releases after the version where they were first added has been released >>>>>> as >>>>>> final. >>>>>> For example if a method is deprecated in, say XE 1.3M2 then the method >>>>>> will be removed in 1.6M1 or after. Of course any major new release can >>>>>> deprecate anything. For example a XWiki 2.0 release is allowed to break >>>>>> backward compatibility (obviously we need to be careful to offer a >>>>>> migration path for users of previous major versions). >>>>>> " >>>>>> >>>>>> Issues: >>>>>> * This seems a bit harsh to me for some of our users/devs in the >>>>>> community. >>>>>> * We're not following which proves to me it's not a good rule >>>>>> * It doesn't say anything about Scripting APIs which require a greater >>>>>> stability in order not to break all wiki pages >>>>>> >>>>>> Definition of a Scripting API: >>>>>> * a Script Service (that's the new way of providing script apis) >>>>>> * a class in the "api" package in xwiki-platform-oldcore (this is the old >>>>>> way of providing script apis) >>>>>> >>>>>> Thus I'd like to propose this new rule: >>>>>> >>>>>> * Deprecated methods can only be removed in the next Release Cycle. For >>>>>> example something deprecated in version N.x can be removed in version >>>>>> N+1.y >>>>>> where x and y can be anything. This is logical since N+1 means a new >>>>>> major >>>>>> release and it's common to understand that major releases have no >>>>>> guarantee >>>>>> of API compatibility (See >>>>>> http://en.wikipedia.org/wiki/Software_versioningfor example). >>>>>> * For scripting APIs we can remove deprecated API only after 4 Release >>>>>> Cycles. For example since we're in 4.x this means we >>>>> >>>>> >>>>> Why four ? isn't it too much ? >>>> >>>> The reason I proposed 4 is because nowadays there still are quite a few >>>> XWiki 1.x instances in the wild so if people have coded apps on 1.x and >>>> then upgrade to 4.0 (for ex) it would be nice if their app still works. >>>> However I think it's ok to not support apis done in 0.9. And next year it >>>> would be ok to drop 1.x api support, etc. >>>> >>>> It's long but then we can see in the wild that it's important we provide >>>> stable scripting apis for users since they're used a lot while java apis >>>> are used by more savvy user (developers) and thus having a shorter >>>> removing cycle for them (1 year) should be ok. >>>> >>>> What would you like to propose instead? >>> >>> I'd rather we had no hard rules lest dogmatic adherence to the rules >>> becomes an excuse not to fulfill our obligation to do what's best for the >>> software. >>> I'm not exactly sure what `break' means since there's no reason I can see >>> for these functions to be removed from the compatibility aspect. >> >> The reason for having a well-defined rule is: >> >> * I think it's better than having to send a vote every time we want to >> remove a deprecated api. It certainly is much simpler. >> * Publicly document it so that our users will know about this rule and adapt >> their deprecation replacement strategy as a consequence >> >> I really think we ought to publish our deprecation and removal policy. >> >>> I propose: >>> >>> #1 Move remaining deprecated scripting API methods from oldcore into >>> legacy-oldcore compatibility aspect. >>> That means these: >>> http://nexus.xwiki.org/nexus/service/local/repositories/releases/archive/org/xwiki/platform/xwiki-platform-oldcore/4.0-milestone-1/xwiki-platform-oldcore-4.0-milestone-1-javadoc.jar/!/index.html >> >> This is *already* our strategy, see the "2-step" strategy defined here: >> http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HDeprecation26LegacyStrategy >> >> Everyone is already supposed to do this and do this regularly. The issue is >> that before being able to move a lot of code we need to fix a lot of >> deprecation usages. >> >> <OT>It could be nice to organize a "deprecation day" where we try to squash >> as many deprecation usages as possible</OT> >> >>> #2 Get xwiki-enterprise building and testing with xwiki-platform-oldcore >>> instead of xwiki-platform-legacy-oldcore. >>> Add an xwiki-enterprise-legacy-jetty-hsql build profile so that we can test >>> in parallel, with and without legacy-oldcore. >>> I ran the UI tests and it appears that we have a few dependencies on >>> legacy-oldcore. IMO this is very bad. >> >> This is very very bad and goes against our current policy indeed. >> >>> However it doesn't look like we have too many. >>> Lets get it running, see the failing tests, report the issues, then fix >>> them. >> >> This is a very good idea and I'm all for it. >> >>> #3 Stop shipping legacy-oldcore by default. Users can always swap >>> platform-oldcore for it on their own. >> >> It's not just oldcore, we have several legacy modules and theoretically we >> can have as many as we have modules. >> >> I don't think we cans stop shipping a distribution with legacy modules but >> what would be nice is to start shipping a distribution without legacy >> modules. We could even highlight this one as first listed to raise awareness. >> >>> #4 Aggressively move deprecated internal (non-script api) code into the >>> compatibility aspect, this will allow us to simplify the oldcore, and >>> potentially even remove dependencies. >> >> This is already our strategy. Again for some cases it's hard but I'm all for >> it. A lot of us introduce new APIs but don't update the code to use the new >> API creating a lot of deprecation usages suddenly. I'm all for this too. >> >>> If we want to stall, we can stall at #3, having 1, 2, and some of 4 taken >>> care of will make the final decision the flip of a switch. >> >> This is all great but it doesn't solve the VOTE. It's a different topic and >> something we've already VOTED and doing. I agree it would be nice to do it >> more aggressively but it's very different from the deprecation policy I'd >> like to find an agreement on. >> >> Unless I misunderstood you and your proposal is to NEVER remove deprecated >> APIs, which is a solution of course. I'm a bit afraid of the consequences. > > Actually this is not a bad idea. I've thought about it and couldn't find a > real blocker to this strategy of never removing deprecated APIs. Some > thoughts though: > > * When we remove a class to replace it with another one we need to invent a > mechanism in the main code to allow pluggability. Sometimes this is nice to > have but sometimes it's a bit contrived and it would be nice to remove this > pluggability when it's no longer needed. Not that bad though. > * We currently have no way to know if something in legacy is working since > we're not using it anymore :) The only solution I could think of would be to > add some functional tests to prove that these old apis still work.
Writing additional tests for deprecated code means we are basically maintaining it, I think this is the wrong direction, not to mention feasibly. I suggested running the normal tests twice just to make sure legacy has not broken something which we do use. > > So do we want to keep our deprecated APIs forever with a special vote each > time we really need to remove something from legacy? This only would make any sense in the context of legacy as a method graveyard which was not shipped and only provided to users hoping to fix their broken apps. That said, unused unmaintained code in an evolving codebase is just as bad if not worse than nonexistant code so +1 to removing things from legacy. WDYT of deprecating in place for a small span of time, then moving to -legacy for a larger span of time and finally removing from legacy. This paired with not shipping -legacy by default would give users a stepping stone between "works" and "broken". Caleb > > Thanks > -Vincent > >> BTW I'd like to update our current strategy documentation to a 3-step >> strategy: >> * Step 1: deprecate >> * Step 2: move to legacy modules (this means removing our usages of the >> deprecated apis) >> * Step 3: remove from legacy modules <-- This is what we're voting on here >> >> i.e. we could do step3 only when we've done steps 1 and 2 first. This is a >> good strategy IMO because it means that we would have done step2 which is >> required to be able to remove a deprecated api anyway… ;) >> >> Thanks >> -Vincent >> >>> Caleb >>> >>> >>> >>>> >>>> Thanks >>>> -Vincent >>>> >>>>>> can remove deprecated APIs from 0.x releases. And when we start 5.x we >>>>>> will be able to remove deprecated scripting apis deprecated in 1.x. >>>>>> >>>>>> Here's my +1 >>>>>> >>>>>> Thanks >>>>>> -Vincent > > _______________________________________________ > devs mailing list > [email protected] > http://lists.xwiki.org/mailman/listinfo/devs > _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
