[hibernate-dev] HV: Handling of deprecations

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