Remove ability to merge detached entities

UPGRADE.md

@@ -1,5 +1,15 @@
 # Upgrade to 3.0
 
+## BC BREAK: Remove ability to merge detached entities
+
+Merge semantics was a poor fit for the PHP "share-nothing" architecture.
+In addition to that, merging caused multiple issues with data integrity
+in the managed entity graph, which was constantly spawning more edge-case
+bugs/scenarios.
+
+The method `UnitOfWork::merge()` has been removed. The method
+`EntityManager::merge()` will throw an exception on each call.
+
 ## BC BREAK: Removed ability to partially flush/commit entity manager and unit of work
 
 The following methods don't accept a single entity or an array of entities anymore:

lib/Doctrine/ORM/EntityManager.php

@@ -4,13 +4,13 @@
 
 namespace Doctrine\ORM;
 
+use BadMethodCallException;
 use Doctrine\Common\EventManager;
 use Doctrine\Common\Util\ClassUtils;
 use Doctrine\DBAL\Connection;
 use Doctrine\DBAL\DriverManager;
 use Doctrine\DBAL\Exception as DBALException;
 use Doctrine\DBAL\LockMode;
-use Doctrine\Deprecations\Deprecation;
 use Doctrine\ORM\Exception\EntityManagerClosed;
 use Doctrine\ORM\Exception\InvalidHydrationMode;
 use Doctrine\ORM\Exception\ManagerException;
@@ -542,35 +542,15 @@ public function detach($entity): void
     }
 
     /**
-     * Merges the state of a detached entity into the persistence context
-     * of this EntityManager and returns the managed copy of the entity.
-     * The entity passed to merge will not become associated/managed with this EntityManager.
+     * Not supported.
      *
-     * @deprecated 2.7 This method is being removed from the ORM and won't have any replacement
+     * @param object $object
      *
-     * @param object $entity The detached entity to merge into the persistence context.
-     *
-     * @return object The managed copy of the entity.
-     *
-     * @throws ORMInvalidArgumentException
-     * @throws ORMException
+     * @psalm-return never
      */
-    public function merge($entity): object
+    public function merge($object): object
     {
-        Deprecation::trigger(
-            'doctrine/orm',
-            'https://github.com/doctrine/orm/issues/8461',
-            'Method %s() is deprecated and will be removed in Doctrine ORM 3.0.',
-            __METHOD__
-        );
-
-        if (! is_object($entity)) {
-            throw ORMInvalidArgumentException::invalidObject('EntityManager#merge()', $entity);
-        }
-
-        $this->errorIfClosed();
-
-        return $this->unitOfWork->merge($entity);
+        throw new BadMethodCallException('The merge operation is not supported.');
     }
 
     /**