Merge branch 'hotfix/#1257-discriminator-map-changes-documentation'

UPGRADE.md

@@ -1,5 +1,21 @@
 # Upgrade to 2.5
 
+## Minor BC BREAK: discriminator map must now include all non-transient classes
+
+It is now required that you declare the root of an inheritance in the
+discriminator map.
+
+When declaring an inheritance map, it was previously possible to skip the root
+of the inheritance in the discriminator map. This was actually a validation
+mistake by Doctrine2 and led to problems when trying to persist instances of
+that class.
+
+If you don't plan to persist instances some classes in your inheritance, then
+either:
+
+ - make those classes `abstract`
+ - map those classes as `MappedSuperclass`
+
 ## Minor BC BREAK: ``EntityManagerInterface`` instead of ``EntityManager`` in type-hints
  
 As of 2.5, classes requiring the ``EntityManager`` in any method signature will now require 

docs/en/changelog/migration_2_5.rst

@@ -579,6 +579,25 @@ Hydrators are per query instantiated since Doctrine 2.4.
 
 - `DDC-3060 <http://doctrine-project.org/jira/browse/DDC-3060>`_
 
+Minor BC BREAK: All non-transient classes in an inheritance must be part of the inheritance map
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+As of 2.5, classes, if you define an inheritance map for an inheritance tree, you are required
+to map all non-transient classes in that inheritance, including the root of the inheritance.
+
+So far, the root of the inheritance was allowed to be skipped in the inheritance map: this is
+not possible anymore, and if you don't plan to persist instances of that class, then you should
+either:
+
+- make that class as ``abstract``
+- add that class to your inheritance map
+
+If you fail to do so, then a ``Doctrine\ORM\Mapping\MappingException`` will be thrown.
+
+
+- `DDC-3300 <http://doctrine-project.org/jira/browse/DDC-3300>`_
+- `DDC-3503 <http://doctrine-project.org/jira/browse/DDC-3503>`_
+
 Minor BC BREAK: Entity based EntityManager#clear() calls follow cascade detach
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~