On Tue, Feb 12, 2013 at 2:26 PM, Vincent Massol <vincent@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
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
_______________________________________________ devs mailing list devs@xwiki.org http://lists.xwiki.org/mailman/listinfo/devs