Personally, I do not like annotations to describe the stability of an API. If it's public I can use it. The next release is binary and/or source compatible, just document how to migrate. No one is forcing me to upgrade. If I upgrade, I am using a new pile of code and I must deal with that.
Using ".internal" packages is an interesting way to go. But I do like documentation of some kind for things like immutability and thread-safety. We've started going down the path of what I call "extreme versioning" when we create new packages for new incompatible releases. Right now, binary incompatible -> new package (I'm even going to include Maven artifact ID noise here). But what about a change in behavior that is not compatible? Should that not lead to a new package? Commons is a 'special' project because it includes so many components. It would be nice if all components played by the same rules. Strictly speaking, I think we are bound to do so. Gary On Mon, Dec 5, 2011 at 10:21 AM, Christian Grobmeier <grobme...@gmail.com>wrote: > Henri, > > I would love to see this as a Commons recommendation on the Wiki. > As Stefan mentioned, in Compress we have @experimental annons (I > actually added them). > I like the idea to make up a public, rarely to break interface api and > some not so public sometimes to break implementation. Maybe we should > even consider to create an interface jar and an implementation jar of > different versions. On the other hand this makes things complex - but > anyway.... > > Cheers > Christian > > On Sun, Dec 4, 2011 at 11:41 AM, henrib <hen...@apache.org> wrote: > > Keeping track as it evolves based on feedback; > > > > Goal is to allow easy definition, usage and check of stable APIs. > > An annotation and a package naming convention allow the project > developer to > > clearly state when a class/method/field is not part of the stable > contract > > despite a public/protected declaration but only of the internal part of > the > > project. > > > > @internal annotated class/method or *internal* package mean "use this at > > your own maintenance cost"; those are not part of the "public" API. They > can > > be used and extended but are subject to change between versions without > > @deprecated annotations. > > > > Those annotations and conventions should allow feeding a clirr report > with > > the proper information to allow detection of unintended API breakage and > may > > even allow creating IDE plugins to warn about usage. > > > > -- > > View this message in context: > http://apache-commons.680414.n4.nabble.com/RELEASE-PROCESS-Stability-versus-usability-tp4150322p4156552.html > > Sent from the Commons - Dev mailing list archive at Nabble.com. > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > > For additional commands, e-mail: dev-h...@commons.apache.org > > > > > > -- > http://www.grobmeier.de > https://www.timeandbill.de > > --------------------------------------------------------------------- > To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org > For additional commands, e-mail: dev-h...@commons.apache.org > > -- E-Mail: garydgreg...@gmail.com | ggreg...@apache.org JUnit in Action, 2nd Ed: <http://goog_1249600977>http://bit.ly/ECvg0 Spring Batch in Action: <http://s.apache.org/HOq>http://bit.ly/bqpbCK Blog: http://garygregory.wordpress.com Home: http://garygregory.com/ Tweet! http://twitter.com/GaryGregory
