On 03/29/2012 03:46 PM, Vincent Massol wrote: > > On Mar 29, 2012, at 9:29 PM, Caleb James DeLisle wrote: > >> >> >> 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. > > AFAIK this is exactly the current strategy :) > > What's different from what's already written on > http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HDeprecation26LegacyStrategy > ?
Ok sorry I didn't rtfm, I guess we should be clear to the users on how long the deprecated code will stay out of -legacy since we're considering shipping distributions without -legacy included. For this, I think "until the next major version" should be plenty of time. Caleb > > Thanks > -Vincent > >> 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
