23 Feb
2013
23 Feb
'13
11:42 a.m.
On Feb 12, 2013, at 6:30 PM, Marius Dumitru Florea <mariusdumitru.florea(a)xwiki.com>
wrote:
On Tue, Feb 12, 2013 at 2:26 PM, Vincent Massol
<vincent(a)massol.net> wrote:
If you add in 4.3M1 for example, then when we release 6.0M1 we'll automatically remove
the @Unstable annotation.
Of course, the developer who added it (or any other dev) can propose to remove the
@Unstable annotation at any time before that, this is just a safeguard so that we
don't have API that stay unstable forever…
Ideally I would have preferred 1 year as the max time but IMO this is too complex to
implement (since you need to track when each @Unstable annotation was added and review
them all the time). I found it simpler to review once when we start developing N.0M1.
Now I'm not hung on this so if someone has a better idea, please shoot.
IMO we're going to need to review this anyway after we start using it and learn from
experience.
Note that I've just added an @Unstable annotation to 4 new methods in
ModelScriptService and IMO we'll need to add some code in ScriptServiceManager to
generate some logs that the user is using an unstable API (and add a per page console UI
too btw).
Thanks
-Vincent
Hi devs,
Here's my effort to try to put together all that has been said… :)
The idea is that whenever you change an API (adding a new one or changing an existing
one) you go through the list of strategies below, trying to find the first that matches
your use case.
* Strategy 1 (already in place): Whenever possible don't break backward compatibility
and go through a deprecation mechanism:
** Deprecate classes/methods
** Move them to Legacy modules as soon as our code is not using them anymore
** Note: No need to touch CLIRR
* Strategy 2 (new): If possible, code defensively, i.e. put code in internal and open up
when api is stable later on, either when users ask for it or when someone feels it's
the right time
** Note: No need to touch CLIRR
* Strategy 3 (new): If not possible (for example
complete new modules where you wish to separate what will become stable APIs in the future
from internal code) then use the @Unstable annotation at class level (or method level)
** Whenever we work on a new N.0 milestone 1 version, review all existing @Unstable
annotation and for those that were added before N-1.0 remove the annotation
So public APIs 'automatically' become stable after 2 release cycles or
after 2 final releases? E.g. if I added an API annotated with
@Unstable in 4.3 then it becomes stable in 6.0M1 (because it was added
before 5.0) or in 4.5? Thanks,
Marius
> ** Exclude the classes/methods marked @Unstable from CLIRR
>
> * Strategy 4: If the API is stable and the developers wants to break it (change of
signature for example) and all other strategies don't apply, then either:
> ** (new) Just do it and modify the CLIRR exclude. Preferable (but not mandatory) send
a NOTICE email to warn others devs that an API is going to be broken in the next release
> ** If not sure, send a PROPOSAL or VOTE email depending on how important you think
the API to be broken is
>
> WDYT?
>
> Thanks
> -Vincent