Re: [hibernate-dev] Marking API members as incubating
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.