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/3424896cadb3d7ec21edb002a040e4c9b504dde3#commitcomment-2686381
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 <[email protected]> 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 > _______________________________________________ devs mailing list [email protected] http://lists.xwiki.org/mailman/listinfo/devs
