On 5 December 2011 15:42, Gary Gregory <garydgreg...@gmail.com> wrote: > 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 your component is part of a larger application that may not be true, see below. > If I upgrade, I am using a new pile of code and I must deal with that. That's OK if your code is stand-alone at the end of the food chain, and you have control over it. Commons components often are deeply embedded. > 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). See below for the reason why that is generally necessary. > But what about a change in behavior that is not compatible? Should that not > lead to a new package? Depends why the behaviour changed. Is it a bug fix? > 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. I would say the Commons components are special because they are likely to be deeply nested in applications, with many other components depending on them. It may not be possible to upgrade the other components all at once. Some may be impossible to replace. If two components in the same classpath need incompatible versions, it will in general be impossible to update unless the two versions can coexist. That is why we have the rules on package/Maven id changes, so there can be multiple versions of a Commons component on the same classpath, if the need arises. Because package changes are expensive to end users, we try to avoid them if at all possible. That is why it's worth striving for binary compatibility. > 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 --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@commons.apache.org For additional commands, e-mail: dev-h...@commons.apache.org
