3 May
2012
3 May
'12
3:20 p.m.
On May 3, 2012, at 2:47 PM, Marius Dumitru Florea wrote:
On Thu, May 3, 2012 at 10:47 AM, Vincent Massol
<vincent(a)massol.net> wrote:
Yep, I have no solution for this except adding a new interface that extends the old one
and adds new APIs which means doing an instanceof in code requiring access to the new
methods…
The other idea but this is a bit science-fiction would to make the xwiki runtime a
"polymorphic runtime" (™) ;)
This means:
* At runtime, use Byteman or a tool that can change bytecode and when loading a Class
inject behavior. For example if a Job class had a new method MMM added, loading a class
implementing Job would add a default implementation for MMM if such a method doesn't
already exist.
In short this means bringing our compile time aspects to runtime.
That's probably not very easy to do.
Ideas anyone?
Thanks
-Vincent
Hi devs,
We have recently voted a rule where we said that we will do the following:
* Always deprecate APIs
* Always move them to Legacy modules
* And when there's a technical issue to moving stuff to the Legacy module, only then,
send a VOTE to remove an API
(see http://markmail.org/message/tino4ngttflc5i3s).
This means that from now on (starting on 26th of April 2012) we're not allowed to
put excludes in CLIRR.
However I've seen that we have added some CLIRR excludes after the vote was passed.
I believe that the main issue we have is for "young" APIs that are not
considered stable.
Proposal 1: Internal package
=========
* Young APIs must be located in the "internal" package till they become stable.
I propose "internal" to reuse an existing package that we filter when testing
for CLIRR. "internal" means that users should not use this API because it's
considered unstable and can change at any time.
* When a Young API is considered stable enough and we want to open it to public
consumption then we move it from "internal" to its target package (that's
easy to with IDEs). From that point forward any changes to them goes through the standard
mechanism of deprecation/legacy.
* If we want to add a new method to an existing
public API then this should not be considered a "young" API. It's just an
addition to an existing API and thus goes directly to the deprecation/legacy cycle.
It's not clear for me how we can keep backward compatibility when
adding a new method to an interface. What do you put in legacy? * We need to
be careful to isolate "young" APIs from public API so that users don't
inadvertently use "young" unstable APIs by mistake. If not possible then
directly go through the deprecation/legacy cycle.
The advantage of this proposal is that it doesn't change our current practices and is
very easy to verify through CLIRR.
+1
Thanks,
Marius
>
> Proposal 2: Experimental package
> =========
>
> Another possibility I can think of is to introduce a new "experimental"
package instead of reusing the "internal" one. It has the advantage of being
able to follow "young" APIs and ensure they don't stay in that state
indefinitely, while still allowing the user who uses it to notice it's experimental.
>
> Proposal 3: Experimental Annotation
> =========
>
> Another idea is to just use an @Experimental javadoc tag for experimental code. It
has the advantage of using the target package but it has drawbacks:
> * It's impossible for users to notice that they're using Experimental APIs
since when they import a class they won't see anything that'll tell them
they're using a "young" API
> * It's almost impossible to tell CLIRR to exclude those APIs from its checks. The
only way to do this is to modify the source code of the CLIRR plugin AFAIK. Thus we would
need to exclude those manually using CLIRR excludes and thus before we release we would
need to go over the full list of CLIRR excludes to ensure the excludes listed are only for
"young" APIs marked "experimental".
>
> Note that I mentioned javadoc tag and not annotation because I believe we need to add
information about when the Experimental API was first introduced so that we eventually
move it as a proper API by removing the Experimental tag. Maybe we would need a rule such
as: keep that tag for less or equal to 3 full minor releases (i.e. 6 months).
>
> WDYT? Any other idea?
>
> Thanks
> -Vincent