FTR here's what the Hadoop project has defined: https://issues.apache.org/jira/browse/HADOOP-5073
Flume project discussing adopting the Hadoop rules: http://search-hadoop.com/m/3iHzkEPsdG1 And here are the original docs I've used in the past on the Cactus project (which led to the proposal of the "internal" package in XWiki): http://wiki.eclipse.org/Evolving_Java-based_APIs http://wiki.eclipse.org/Evolving_Java-based_APIs_2 http://wiki.eclipse.org/Evolving_Java-based_APIs_3 Package names: http://wiki.eclipse.org/Naming_Conventions#Internal_Implementation_Packages] Conclusion: I think we're good with our "internal packages" for the scope and the @Unstable annotation for the stability. 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
