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

[Gunnar Morling]

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

Indeed we're using some tooling related to this, japicmp:

    https://github.com/siom79/japicmp

And our usage in HV:

    https://github.com/hibernate/hibernate-validator/blob/master/pom.xml#L801..L832

It's not run as part of every build, but instead we take a look at the
report of API/SPI changes it generates before doing a release. This
report is rather verbose, so it's not something we'd release as is for
consumption by users, but it gives a good overview of what has changed
and is a good source for writing the migration guide.

In all fairness it also should be said that the problem probably is
much smaller for HV as our public surface is quite narrow (95% of the
public API are the spec'ed BV API and we only add some small
additions) and we took care of clearly defining and evolving that
public surface in a compatible manner from the get-go.



2017-06-07 10:19 GMT+02:00 Yoann Rodiere <yoann at hibernate.org>:
> 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
>>
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev