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

[Yoann Rodiere]

Hi,

Answers below.

Yoann Rodière
Hibernate NoORM Team
yoann at hibernate.org

On 6 June 2017 at 18:48, Sanne Grinovero <sanne at hibernate.org> wrote:

> == 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?
>

Sure, it makes sense if we don't provide any long-term guarantee of
backward compatibility.


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

Yes. This basically means we don't have a solution for APIs, but... at
least we're aware of that :)


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

I agree with your analysis, but I'm not sure being aware of it and agreeing
that we shouldn't break too much will solve the problem. To me, a big part
of why we have a risk of breaking lots of things is that we currently don't
have the big picture until we write up the migration guide, just before we
release.
Maybe a way to solve the issue would be to write the migration guide
incrementally, with each PR we send?

One way of enforcing this (reminding us to update the migration guide)
would be to have a tool check for API/SPI breaks on *each build*, and make
the build fail by default for any API/SPI change, requiring to at least put
an exclusion in a dedicated file to make it pass. Unless I'm wrong we
currently only do this in the engine/ORM modules. And actually I'm not sure
the current setup works, because I remember breaking SPIs since 5.7 and I
never had any build error relative to SPI breaks...
Anyway, if you agree with that, I can have a look at the tooling we may
use. I suspect other Hibernate projects may already have such tooling in
place (Hibernate Validator in particular).


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

If I remember correctly, that's exactly what we intended to do with 5.8,
except it's beginning to be a rather large intermediate minor itself :D
More seriously, yes, we should probably put less in each release, and in
particular have safeguards so that we don't realize there's too much in a
release when it's too late. But in order to do that, we should (in my
opinion) also have stricter monitoring of our work, and that's probably not
something we want, for various reasons we already discussed (one of them
being that we don't always know expansive and API/SPI-breaking a task will
be before we actually work on it).



>
> Thanks!
> Sanne
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>