On Feb 12, 2013, at 2:38 PM, Sergiu Dumitriu <[email protected]> wrote:
> On 02/12/2013 07:26 AM, Vincent Massol 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 > > I guess this has to be done manually, right? right -Vincent > >> * 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? > > Sounds good. _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
