Deprecate DocumentManager::merge

[malarzm]

The merge method is removed from the ObjectManager interface in doctrine/persistence 3.0 and as such we are free to deprecate (and eventually remove) it as well. Throughout the years the merge operation was one of the most misused functionality across all Doctrine's data mappers. Having said that the merge functionality has its value when caching comes into play, especially since the ODM does not provide a second level cache (like ORM does). Removing merge without any replacement (as we plan) would effectively block users from upgrading to a next major version.

Given the circumstances we're not deprecating merge just yet, consider this issue as a friendly warning instead. If you use merging documents for performance reasons please do let us know! If no (valid TM) objections are raised and enough (TM) time passes we may proceed with deprecation process before the 3.0 release.

[malarzm]

No concerns were raised for a year and a half, scheduling for 2.7.x