On Mar 28, 2012, at 7:10 PM, Denis Gervalle wrote:

On Wed, Mar 28, 2012 at 12:27, Vincent Massol <vincent@massol.net> 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#HDeprecat...

" 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? 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

On Mar 28, 2012, at 9:12 PM, Denis Gervalle wrote:

On Wed, Mar 28, 2012 at 20:03, Vincent Massol <vincent@massol.net> wrote:

...

On Mar 28, 2012, at 7:10 PM, Denis Gervalle wrote:

...

On Wed, Mar 28, 2012 at 12:27, Vincent Massol <vincent@massol.net> 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#HDeprecat...

...

" 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?

At the same time, many feature as probably evolved since 1.x and may still render your application not workable AS IS in 4.x. Think about the skin, even if theorically albatross should still work, I am sure there is many unexpected issue with it, and using it in 4.x would probably not give you much advantage over your 1.x setup... My last experience between 3.1 and 3.4 has already issues. I would understand keeping compatibility so long if you do not introduce alternative, but in most case we do. I do not imagine a user of 1.x that really expect moving to 4.x without some effort, and without expecting some improvement other than a better core system. So, are we really targeting real use case ?

Yes. What you say is not fully true from my POV (and from what I've heard from other users). I've myself installed XARs that were developed in XE 1.1 and they worked mostly without any issue. The only issue I've found were with skin elements (like the search icon, etc) but at the api level all my apps were still working fine. Also, the move from 3.1 to 3.4 is not a valid example. We have made a lot of regression during this time especially with hibernate and we've fixed those so someone moving from 3.1 to 3.5.1 or 4.0 will not have the same problems.

Keeping compatibility is a huge effort in maintenance and may also slow down evolution, and I just found having a so long compatibility field, to be too much compare to our team.

Yes but you're forgetting that we're not an application. We're a development platform which is the same as saying that we're a language. And a language needs stability. You can compare to other dev languages you know and check how frequently they break apis in general...

Also, having different policies for java and scripting is also a complexity, both in term of development and understanding.

Sure but that's not the reality. The vast majority of XWiki users who develop on XWiki are developing in wiki pages. There's only a very small minority that code in java and use the java non-scripting apis.

So I would be in favor to have a single policy for all.

What Thomas propose seems really reasonable IMO, deprecating preferably in N+2.0. This is not a obligation anyway, and on a case by case basis we may still derogate to the rules, if a specific feature seems important to keep. There is no obligation for user to migrate, and with a clear deprecation documentation in the release notes, it should be quite easy to maintain old scripts.

WDYT ?

While it's nice to have the same deprecation strategy both types of API it'll never work. This means that we're allowed to remove now (in 4.0) apis that have been deprecated in 1.x and 2.x. Since the vast majority of XE installs in the wild are using XE 2.x they'll all have a lot of work to do when they upgrade to 4.x (since they'll make the jump from 2.x to 4.x). I have the strong feeling that people using XE in production (like Ludovic) would not like this very much… Let's get more feedback from other committers. Thanks -Vincent PS: I'd personally be more than happy to remove deprecation as soon as possible but I also understand that we have to be kind to our users.

...

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

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 <vincent@massol.net> 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#HDeprecat...

" 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...

This is *already* our strategy, see the "2-step" strategy defined here: http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HDeprecat... 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. 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

On 03/29/2012 02: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 <vincent@massol.net> 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#HDeprecat...

" 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 agree in so far as it's giving the users an idea of how long they can expect deprecated functions to last. If they last longer, as they almost always do, that should be ok, it's just that they are past the point where a user can rely on them.

...

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...

This is *already* our strategy, see the "2-step" strategy defined here: http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HDeprecat...

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>

+1

...

#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.

Will propose separately.

...

#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 meant to mention this, IMO we should start with legacy-oldcore since it's the one with scripting APIs. We could do a review later.

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.

Why not? New users will never know that they existed, which is what we want lest they begin using them. Old users will always have the option of adding the legacy modules back in. IMO it's a very small price to pay to ask users to tinker with some jar files to have their deprecated functions back, I'm afraid if we can't expect that of them, we have very little hope of ever removing anything. I also like Denis's idea of an extension but only if there is significant demand. We must consider the possibility that nobody actually misses it.

...

#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.

Sorry for being slow on the uptake, if your vote is to remove code from the compatibility aspect, my answer is 0, it serves no purpose I can see since the compatibility aspect itself should not be distributed to new users. Also sorry for hijacking the thread. Caleb

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… ;)

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 devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs

On Mar 29, 2012, at 10: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 <vincent@massol.net> 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#HDeprecat...

" 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...

This is *already* our strategy, see the "2-step" strategy defined here: http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HDeprecat...

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.

* We need to introduce aspects in legacy modules other than oldcore. This is ok for me. Thanks -Vincent

So do we want to keep our deprecated APIs forever with a special vote each time we really need to remove something from legacy?

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

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 <vincent@massol.net> 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#HDeprecat... > > " > 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...

This is *already* our strategy, see the "2-step" strategy defined here: http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#HDeprecat...

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#HDeprecat... ? 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

Here's a summary email (as I understand it!). Ok if I understand correctly, what you'd like to propose is: ============================================ * Distribute without legacy by default * Provide a way for users to add the legacy modules if they need them (details to be defined for how they can do this - a zip containing jars to drop in WEB-INF/lib, installation from the EM, etc) * When we deprecate an API we keep it in the main modules (i.e. non-legacy modules) for a while. You're suggesting till the next major version, i.e. a full Release Cycle (which is 1.2 years). This is the big difference with now where we move to the legacy modules ASAP because we want to be sure that no code we have uses the deprecated APIs. By keeping them in our codebase we wouldn't benefit from this nice "feature". So we'd need a solution for that. * We never remove code from legacy modules ? (I think you mentioned you' d be for removing but I haven't really understood the strategy to do so) Personally I'd prefer the following: ========================== * Distribute without legacy by default * Make it very easy for a user to add the legacy modules by providing a distribution containing the legacy modules that is clearly visible in the download page (but less visible that the distribution without legacy modules) * Continue to move deprecated APIs to legacy modules *ASAP* (i.e. as soon as our code is clean and doesn't use the newly deprecated APIs) * Never remove from the legacy modules by default but when we really need to do so (for some technical reason for example), do it on a case by case basis and send a VOTE to do so This would ensure that: * New users very quickly use the newest APIs (they won't even see the old APIs). * Older users are not broken * When someone upgrades he can easily try using the new distribution without legacy and if it breaks some of his code he can either fix his code or add the legacy modules WDYT? Thanks -Vincent [snip]

On Thu, Mar 29, 2012 at 22:41, Vincent Massol <vincent@massol.net> wrote:

Here's a summary email (as I understand it!).

Ok if I understand correctly, what you'd like to propose is: ============================================

* Distribute without legacy by default * Provide a way for users to add the legacy modules if they need them (details to be defined for how they can do this - a zip containing jars to drop in WEB-INF/lib, installation from the EM, etc) * When we deprecate an API we keep it in the main modules (i.e. non-legacy modules) for a while. You're suggesting till the next major version, i.e. a full Release Cycle (which is 1.2 years). This is the big difference with now where we move to the legacy modules ASAP because we want to be sure that no code we have uses the deprecated APIs. By keeping them in our codebase we wouldn't benefit from this nice "feature". So we'd need a solution for that. * We never remove code from legacy modules ? (I think you mentioned you' d be for removing but I haven't really understood the strategy to do so)

Personally I'd prefer the following: ==========================

* Distribute without legacy by default

+1

* Make it very easy for a user to add the legacy modules by providing a distribution containing the legacy modules that is clearly visible in the download page (but less visible that the distribution without legacy modules)

+0, following the scenario you describe below, I see no point having a full legacy distribution. What the user needs is a way to add the legacy module alone. Unless we could do that with the EM, at least a user may put some jar in the lib folder IMO. I admit that this is questionable for the war distribution. What I am afraid of, is the hesitation of the user about what distribution to take, and the multiplication by two of all of them.

* Continue to move deprecated APIs to legacy modules *ASAP* (i.e. as soon as our code is clean and doesn't use the newly deprecated APIs)

+1

* Never remove from the legacy modules by default but when we really need to do so (for some technical reason for example), do it on a case by case basis and send a VOTE to do so

+1

This would ensure that: * New users very quickly use the newest APIs (they won't even see the old APIs). * Older users are not broken * When someone upgrades he can easily try using the new distribution without legacy and if it breaks some of his code he can either fix his code or add the legacy modules

WDYT?

Thanks -Vincent

[snip]

_______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs

-- Denis Gervalle SOFTEC sa - CEO eGuilde sarl - CTO

On Wed, Mar 28, 2012 at 11:28 PM, Caleb James DeLisle <calebdelisle@lavabit.com> 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 <vincent@massol.net> 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#HDeprecat...

" 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.

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...

#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. 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 actually not expected and should be fixed, the current rule is not never use anything coming from legacy packages. It's technically enforced at java level but it's harder at wiki page level.

#3 Stop shipping legacy-oldcore by default. Users can always swap platform-oldcore for it on their own.

#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.

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.

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 devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs

_______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs

-- Thomas Mortagne

On Mar 28, 2012, at 8:06 PM, Thomas Mortagne wrote:

On Wed, Mar 28, 2012 at 12:27 PM, Vincent Massol <vincent@massol.net> 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#HDeprecat...

" 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_versioning for example).

I don't like it too much, that mean you can deprecated something in 3.5 and remove it in 4.0.

I had thought about this of course. But my rationale was that 4.x is a major release compared to 3.x and thus we are "allowed" to break backward compatibility.

I think I would prefer to have a rule saying that a full cycle must be pasted before you remove something and that you remove things in N+2.0.

I hope you're not suggesting that we can only remove in X.0 releases (4.0, 5.0, etc). I would be fine with waiting a full cycle. This would mean that stuff deprecated in N.x can be removed in N+2.y where x and y are any value. This means that deprecations added in 2.0 for example can only be removed in 4.0 (i.e. 2.5 years after since a cycle is about 1.2-1.3 years). I find this a bit long for the java non scripting apis. We could also say 6 minor releases (since a cycle is exactly 6 minor releases) but I thought it would be nicer to align on cycles since they correspond to major versions and I wanted to not have to change the rule if we decide to change the cycle duration... What do others think? Thanks -Vincent PS: I stupidly though it was going to be an easy vote ;)

...

* For scripting APIs we can remove deprecated API only after 4 Release Cycles. For example since we're in 4.x this means we 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

On Wed, Mar 28, 2012 at 9:36 PM, Vincent Massol <vincent@massol.net> wrote:

On Mar 28, 2012, at 8:06 PM, Thomas Mortagne wrote:

...

On Wed, Mar 28, 2012 at 12:27 PM, Vincent Massol <vincent@massol.net> 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#HDeprecat...

" 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_versioning for example).

I don't like it too much, that mean you can deprecated something in 3.5 and remove it in 4.0.

I had thought about this of course. But my rationale was that 4.x is a major release compared to 3.x and thus we are "allowed" to break backward compatibility.

...

I think I would prefer to have a rule saying that a full cycle must be pasted before you remove something and that you remove things in N+2.0.

I hope you're not suggesting that we can only remove in X.0 releases (4.0, 5.0, etc).

N+2.0 was actually the minimum version in which you are allowed to remove APIs and were is should be done but if we forget some we can remove them later of course

I would be fine with waiting a full cycle. This would mean that stuff deprecated in N.x can be removed in N+2.y where x and y are any value. This means that deprecations added in 2.0 for example can only be removed in 4.0 (i.e. 2.5 years after since a cycle is about 1.2-1.3 years).

I find this a bit long for the java non scripting apis.

We could also say 6 minor releases (since a cycle is exactly 6 minor releases) but I thought it would be nicer to align on cycles since they correspond to major versions and I wanted to not have to change the rule if we decide to change the cycle duration...

What do others think?

Thanks -Vincent

PS: I stupidly though it was going to be an easy vote ;)

...

...

* For scripting APIs we can remove deprecated API only after 4 Release Cycles. For example since we're in 4.x this means we 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 devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs

-- Thomas Mortagne