FTR I've just documented the Unstable annotation here: * http://dev.xwiki.org/xwiki/bin/view/Community/DevelopmentPractices#H40Unsta… * http://platform.xwiki.org/xwiki/bin/view/DevGuide/API Note that I'm not especially fond/proud of the max time strategy we have since it can lead to APIs staying for 2 years but at least it makes it easy to implement by checking for @unstable before each "N Milestone 1" release. Another option would be to automate the check in a Maven plugin (by reading annotation and then reading @since javadoc tag) and keep @unstable code only for , say, 6 major releases (which corresponds to 1 cycle length). Thanks -Vincent