23 Oct
2012
23 Oct
'12
1:17 p.m.
Hi Edy,
Thanks for joining in! :)
See below
On Oct 23, 2012, at 12:52 PM, Eduard Moraru <enygma2002(a)gmail.com> wrote:
Hi,
I am +1 for option 3), but I would actually prefer it that, instead of
adding a new annotation by ourselves (@Experimental), we reuse java's
deprecation mechanism [1] (@Deprecated annotation + @deprecated javadoc).
That's different. This is not about deprecated code, it's about new code, i.e. the
exact opposite :)
This way:
- users will be warned directly in the IDE to stay away from those APIs
- the compiler and other existing tools will warn
about using the APIs
- we can specify additional details and explanations in the @deprecated
javadoc
- the APIs can be public so we don`t need to move them around afterwards
and we can avoid possible problems related to this; we just remove the
@Deprecated annotation (as already mentioned in the @Experimental case).
- we avoid complexity and headaches by not letting the deprecation/legacy
process get in the way of the development of the new feature
Yes of course now personally I don't like 3 at all because it's very very
maintenance-oriented (clirr excludes for example) and is going to cause a big mess: As I
said in my original email the problem is that there's no rule to remove @Experimental
so what will happen is that you'll find @Experimental code that stays in this state
forever, 5 years after it's been started because there are always stuff to improve
(it's the "1.0 syndrome").
I'm personally very very close to -1 solution 3 because it's almost the same as
not doing anything.
For me the only real answer is to do what Eclipse used to do (I don't know if they
still do it) which is to:
- code defensively, i.e. always put new code in the internal package (FTR I took this
notion of internal from them, see
http://jakarta.apache.org/cactus/participating/apis.html)
- open up APIs based on need. This means that whenever someone (a user) needs an API he
reports it and we then open it (if we consider the API is stable at the time and it's
a valid need)
- once it's opened go through the deprecation strategy
Note that we've done that in a few places where we have component interfaces that are
internal ATM. It's a good strategy to stabilize an API.
What we would need to do is in the Developer guide on xwiki.org make it more visible that
devs should not use internal package and if they miss an API to ask at such place for one
(we could even have a jira issue type for that).
Thomas and Denis argued that it's hard to do so for new domains like the new rights
implementation. I still don't understand why. Could you guys explain what would have
been difficult with the strategy above?
Now the only problem I see with the above is that it
would be hard to
oh it's far from being the "only" problem ;) Just to cite 3 issues:
- clirr excludes are very hard to manage/maintain and a pain
- when to move out of "young api" is not defined
- wrong semantic of deprecated
Thanks
-Vincent
programatically generate a list of young APIs, since
there is no clear
differentiation between deprecated and young API (other than the comment in
the @deprecated javadoc). I don`t know if this is such a big problem, since
the main goal is to keep users from using the APIs (for a while at least),
or, if they do, to make them aware that they will need to refactor in the
coming future.
Thanks,
Eduard
----------
[1]
http://docs.oracle.com/javase/1.5.0/docs/guide/javadoc/deprecation/deprecat…
On Thu, May 3, 2012 at 4:48 PM, Vincent Massol <vincent(a)massol.net> wrote:
On May 3, 2012, at 3:40 PM, Thomas Mortagne wrote:
There's no issue with adding new methods with proposals 1 and 2 since
clirr will not even check them :)
With 3) it's harder since you'll need to manually add CLIRR excludes. The
problem with CLIRR excludes is that you can only exclude a full file thus
potentially hiding breakages. The other issue is that we'll need to review
all CLIRR excludes one by one to verify if they're valid (ie code tagged
experimental) or not (in which case deprecation+legacy should be used
instead).
I'm fine with strategy 3) but it's really important to have a limit as to
how long an api remains experimental because otherwise we're going to have
a lot of experimental apis that will never make it user-public and users
are going to start using them and then be broken.
Thanks
-Vincent
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs
_______________________________________________
devs mailing list
devs(a)xwiki.org
http://lists.xwiki.org/mailman/listinfo/devs On Thu, May 3, 2012 at 3:24 PM, Denis Gervalle
<dgl(a)softec.lu> wrote:
> 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 !
Actually we can have an annotation, since we can pass a description string
:)
So using an annotation is better than a javadoc tag.
It also allows to relatively easily list all experimental apis with a tool
that finds annotations statically. We're going to need this to put in the
RN the list of experimental APIs.
>> 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.
Pretty much the same concerns than Denis: it's not as easy as you
think to change package of a big project like rights or extension
manager all the sudden.
But I would vote -1 for 1) and -0 for 2) which is a bit better.
IMO 3) is enough even if not perfect either.
Also about adding new methods, that's really not the main issue of an
experimental API in which we can potentially rename a bunch of methods
because of a design change and an old API has the exact same issue so
none of the proposal help in any way for this.