commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From sebb <>
Subject Re: [RELEASE PROCESS] Stability versus usability
Date Sun, 04 Dec 2011 16:22:58 GMT
On 4 December 2011 10:41, henrib <> wrote:
> Keeping track as it evolves based on feedback;
> Goal is to allow easy definition, usage and check of stable APIs.

+1, agree that we need to be clearer about what the intended external API is.

> 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.


I prefer the use of a separate internal/experimental package name;
seems much more obvious than an embedded annotation.
Also much more obvious when setting up Clirr exclusions.

I think it's worth having both internal and experimental packages (and
- internal = not likely ever to be part of the external API
- experimental = may one day become part of the external API

However, I'm not yet sure how we get around the binary
incompatibilities that result from renaming a package to internal or
experimental (the reverse should be OK, as we don't promise anything)

> 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.

Clirr can already be told to ignore packages and classes.
If it were possible to control this via annotations, I would hope that
the report would show which classes had been excluded from
At least with explicit exclusions in the POM it's fairly easy to see
this information in one place.

To unsubscribe, e-mail:
For additional commands, e-mail:

View raw message