On 03/28/2012 03:36 PM, Vincent Massol wrote:
On Mar 28, 2012, at 8:06 PM, Thomas Mortagne wrote:
On Wed, Mar 28, 2012 at 12:27 PM, 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_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.
I agree with Vincent here. Internal APIs are not something that should
be widely used. Most of the Java code is written by us, so we can update
all the platform code. If others write Java code using the old core, or
some components, they'll probably have an easier time adjusting.
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 ;)
Nothing's easy...
* 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
--
Sergiu Dumitriu
http://purl.org/net/sergiu/
_______________________________________________
devs mailing list
[email protected]
http://lists.xwiki.org/mailman/listinfo/devs
