3 May
2012
3 May
'12
3:24 p.m.
On Thu, May 3, 2012 at 9:47 AM, Vincent Massol <vincent(a)massol.net> wrote:
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.
This is not always so easy. It really depends on what we are working on. If
this is a small, or minor addition, this should works, but for really new
experimental features, this does not fit (ie: security component). First,
you will mixup internal and experimental, which will not shows the intends
and not helps collaborating on the new feature. Second, this will also
influence the place for tests, which will need to be moved later as well.
Third, you will not see potential access issue (package access), since you
will mix packages that will be later split.
* 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.
* 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.
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.
This should solve most of the above inconvenient, but I am not sure we
really need that for new feature. Declaring the feature as experimental in
the RN should be enough IMO.
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).
But you have titled Annotation, which is confusing !
WDYT? Any other idea?
I would be +0 for a mix of 1) and 2) depending on the situation, since 3)
does not really help. I am not sure that cases motivating 2) really need it
and that it is not overkill since recent major features are always known to
be subject to some early deprecation and that we already list all
deprecation in the RN so you may adapt your code rather quickly.
Thanks
-Vincent
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
--
Denis Gervalle
SOFTEC sa - CEO
eGuilde sarl - CTO