[hibernate-dev] HV: Handling of deprecations

[Emmanuel Bernard]

For such drastic moves, Hibernate Search has used the migration page on the wiki to alert people. Not ideal but it works.

Emmanuel

On 1 avr. 2012, at 11:56, Gunnar Morling wrote:

> Hi all,
> 
> Hardy and I have been discussing approaches for deprecating certain
> features in Hibernate Validator [1], and we thought it might be a good
> idea to get some more feedback on this from you folks.
> 
> Basically we've identified two areas of deprecation which need to be addressed.
> 
> One are changes related to the separation of API, SPI and internal
> classes [2]. Here we need to move some classes around (e.g. from API
> to SPI). Originally we thought about adding deprecation markers
> (@Deprecated("Will be removed in a future release")) in HV 4.3 and
> provide the replacements in HV 5. But then we started to wonder
> whether that's actually a good approach as it gives clients
> deprecations which they effectively can't get rid of as of HV 4.3.
> Only when HV 5 is released they can do that, and in fact then
> immediately have to, since the old API will be gone.
> 
> So a better approach might be to add the deprecations *and* the
> replacements in HV 4.3 and remove the old classes in HV 5. This would
> give clients one release time to act upon the deprecation, but would
> require us to keep several classes twice (old and new version).
> 
> The other area of deprecation is the API for method validation. This
> will be standardized in BV 1.1 (=HV 5), while we currently have a
> proprietary API for this in HV. We can't add the new API to HV 4.3 as
> it isn't finalized yet. I see two options for this:
> 
> * Don't do anything related in HV 4.3; Deprecate the old API and add
> the new one in HV 5; remove the old one in 5.1.
> Pro: no immediately breaking changes for clients, deprecations are
> done as originally intended.
> Con: We'd have the old and the new API in HV 5. Originally we didn't
> want that due to complexity reasons.
> 
> * Add deprecation markers as means of heads-up for users to 4.3;
> remove the old and add the new API in HV 5.
> Pro: Likely easier for us as we don't have to maintain to APIs.
> Con: Immediately breaking changes for clients in HV 5, they have to
> immediately adapt their code when upgrading to HV 5.
> 
> I'm not really sure which is the better option here. Given that method
> validation is the biggest new feature of BV 1.1 and HV 5 will be the
> first release to implement that new version of the spec, I think it
> would be ok if that release breaks clients without a previous
> deprecation period. On the other hand it might actually be not that
> complex to keep the old and the new API in HV 5 and remove the old one
> in 5.1.
> 
> So what do you think? Are there clearly defined guidelines on how to
> handle this for the other Hibernate products (ORM, Search etc.)?
> 
> Thanks,
> 
> --Gunnar
> 
> 
> [1] https://hibernate.onjira.com/browse/HV-561
> [2] https://hibernate.onjira.com/browse/HV-557
> [3] https://hibernate.onjira.com/browse/BVAL-241
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev