25 Feb
2013
25 Feb
'13
1:49 p.m.
Hi,
Thomas just raised an issue on this topic. I've added the "@unstable"
annotation to a new getDocument() method he added to the XWiki class in 5.0M1 and Thomas
does not think it's right to do so:
https://github.com/xwiki/xwiki-platform/commit/3424896cadb3d7ec21edb002a040…
This raises the question as to when to use "@Unstable" for new APIs.
I thought the strategy outlined in the mail below was clear on that but it seems not,
which I why I'm sending this email.
Here's my POV:
"
Actually I think we should always start by adding @Unstable annotations to all new APIs at
least so that it can be there for a few releases to see how the API behaves and is used
and give time for devs and others to give any remark about it. If we don't do this
then as soon as the current version is released you're stuck with the API and have to
go through deprecation if you need to modify it... better code defensively!
"
WDYT?
Thanks
-Vincent
On Feb 12, 2013, at 1:26 PM, Vincent Massol <vincent(a)massol.net> wrote:
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
** 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