On Thu, Mar 29, 2012 at 08:20, Vincent Massol <[email protected]> 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. > Couldn't this be achieved (in most case) using a legacy extension installable from the extension manager ? I am not sure providing two distribution is good, it increase the work to release, it increase the complexity for newcomer, ... > > > #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. > > 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… ;) > I fully agree. Why not reduce our engagement to keep an API to a shorter period, the one proposed by Thomas seems reasonable to me, and at the same time, keep in legacy as much as possible, even after that period elapse ? Only removing what became really too hard to maintain, but only when the initial period elapse. > > 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 > -- Denis Gervalle SOFTEC sa - CEO eGuilde sarl - CTO _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
