[hibernate-dev] HV: Handling of deprecations

[Gunnar Morling]

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