[hibernate-dev] Marking API members as incubating

[Steve Ebersole]

On Wed 10 Jul 2013 04:07:33 PM CDT, Gunnar Morling wrote:
>     I sometimes think about a similar approach (in terms of using
>     annotations) to marking the API/SPI/INTERNAL split.
>
>
> An interesting idea. Would this mean to add annotations to every type?
> If so, I'm not sure though how well annotations would "scale" here.
> Also e.g. exporting API types in OSGi manifests is centered around
> packages.

Ideally I'd like to be able to apply it to packages as well.  In terms 
of ORM, for example, it would be nice to annotate the 
org.hibernate.metamodel package on master and 4.x branches as 
@Incubating (or whatever annotation we use).  I guess it depends on the 
breadth of the new feature.  If its changes/adds are small in number 
maybe its enough to annotate just the changed/added contracts.

You are correct about OSGi manifests being package centric.  However, I 
was getting at something that is a bit more fine-grained in an attempt 
to further sub-categorize SPI contracts in terms of intended usage.  
Some SPI contracts are meant simply to expose information to SPI, 
whereas other SPI contracts define the SPI.  In the first case we 
support the intended usage of those contracts; in the latter case we 
support certain SPI providers, in some cases application-supplied.  
Dunno if its useful generally, but I know of one hat I sometimes wear 
where this would be useful.

Of course, we could also support @SPI, @API, @Internal on packages 
only.  Packages without classification would be considered @API, much 
like we do today with the package-naming approach.