28 Mar
2012
28 Mar
'12
10:55 p.m.
On 03/28/2012 03:36 PM, Vincent Massol wrote:
On Mar 28, 2012, at 8:06 PM, Thomas Mortagne wrote:
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.
On Wed, Mar 28, 2012 at 12:27 PM, Vincent
Massol<vincent(a)massol.net> wrote:
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.
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#HDepreca…
"
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 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 ;)
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/