[hibernate-dev] Let's avoid @hsearch.experimental javadoc tags in SPI

[Sanne Grinovero]

== SPI have very long guarantees, anyway

Considering that an SPI contract has relatively low SLAs I'd like to
be way more "aggressive" in the removal of "this is experimental"
notices.

I'd also ask you all to consider not marking them as such, especially
if the issue at hand feels properly sorted out.

Most typically we'll have a notice like "This contract is currently
under active development ".

Anything which is marked as such and yet has not changed since the
last minor release should no longer qualify as "active development",
so we should clean it up and avoid scaring away potential users for no
reason.

WDYT?

== What about API ?

I am going to propose cleaning up the "experimental" tag from some
selected APIs as well, yet in that case I don't think we should apply
a similar reasoning as SPI (development activity) as time is not the
right indicator.

Some API has been marked experimental for a long time for good
reasons: we might not have had the bandwidth (or interest) of
finishing some related issue which could be essential for the feature
to be actually used, and it might be problematic to fix such an half
baked feature w/o being ale to make changes in the contract.

== Reminder on changes

Since we're on the subject... the API/SPI/impl classification is not
black and white so bear in mind that any change we make will annoy
someone.

It's a tradeoff, but when you're making *any* change and have the
opportunity to keep the contract backwards compatible, consider doing
so. @Deprecated is a nice annotation.
Of course this is not a reaction on any specific change; if any I'm
just uncomfortable that I'm going to break a lot myself, and my own
experience is that one can deal with some limited amount of
compilation|compatibility issues but if we push too many "SPI & SPI-
changes" in a single release people will get stuck on the older
versions.

We need to enable people to iterate in smaller milestones which are
simpler to handle; if we're doing too much let's just make more
intermediate minor releases.

Thanks!
Sanne