Add deprecation message for EM#clear($entityName)

UPGRADE.md

@@ -82,6 +82,14 @@ restful operations, you should look at alternatives such as [JMSSerializer](http
 Final keyword will be added to the `EntityManager::class` in Doctrine 3.0 in order to ensure that EntityManager
  is not used as valid extension point. Valid extension point should be EntityManagerInterface.
 
+## Deprecated `EntityManager#clear($entityName)`
+
+If your code relies on clearing a single entity type via `EntityManager#clear($entityName)`,
+the signature has been changed to `EntityManager#clear()`.
+
+The main reason is that partial clears caused multiple issues with data integrity
+in the managed entity graph, which was constantly spawning more edge-case bugs/scenarios.
+
 ## Deprecated `EntityManager#flush($entity)` and `EntityManager#flush($entities)`
 
 If your code relies on single entity flushing optimisations via

lib/Doctrine/ORM/EntityManager.php

@@ -29,6 +29,7 @@
 use Doctrine\ORM\Query\FilterCollection;
 use Doctrine\Common\Util\ClassUtils;
 use Throwable;
+use const E_USER_DEPRECATED;
 use function trigger_error;
 
 /**
@@ -555,6 +556,13 @@ public function clear($entityName = null)
             throw ORMInvalidArgumentException::invalidEntityName($entityName);
         }
 
+        if ($entityName !== null) {
+            @trigger_error(
+                'Calling ' . __METHOD__ . '() with any arguments to clear specific entities is deprecated and will not be supported in Doctrine 3.0.',
+                E_USER_DEPRECATED
+            );
+        }
+
         $this->unitOfWork->clear(
             null === $entityName
                 ? null

tests/Doctrine/Tests/ORM/EntityManagerTest.php

@@ -309,6 +309,15 @@ public function testClearManagerWithNullValue()
         $this->assertFalse($this->_em->contains($entity));
     }
 
+    public function testDeprecatedClearWithArguments() : void
+    {
+        $entity = new Country(456, 'United Kingdom');
+        $this->_em->persist($entity);
+
+        $this->expectDeprecationMessage('Calling Doctrine\ORM\EntityManager::clear() with any arguments to clear specific entities is deprecated and will not be supported in Doctrine 3.0.');
+        $this->_em->clear(Country::class);
+    }
+
     public function testDeprecatedFlushWithArguments() : void
     {
         $entity = new Country(456, 'United Kingdom');