commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gary Gregory <garydgreg...@gmail.com>
Subject Re: [RELEASE PROCESS] Stability versus usability
Date Mon, 05 Dec 2011 15:42:43 GMT
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 <grobmeier@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 <henrib@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-unsubscribe@commons.apache.org
> > For additional commands, e-mail: dev-help@commons.apache.org
> >
>
>
>
> --
> http://www.grobmeier.de
> https://www.timeandbill.de
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@commons.apache.org
> For additional commands, e-mail: dev-help@commons.apache.org
>
>


-- 
E-Mail: garydgregory@gmail.com | ggregory@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

Mime
  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message