HHH-12267 - Update migration guide to cover Generators name scope changes

migration-guide.adoc

@@ -32,20 +32,67 @@ reverts to expecting zero-based binding.
 
 === Change in the `@TableGenerator` stored value
 
-In order to be compliant with JPA specifications, the value stored by Hibernate 5.3 in the Table used by the `javax.persistence.TableGenerator` is the last value generated.
+In order to be compliant with the JPA specification, the sequence value stored by Hibernate 5.3 in the database table used by the `javax.persistence.TableGenerator`
-Previous versions of Hibernate instead stored the next value to be used.
+is the *last* generated value. Previously, Hibernate stored the *next* sequence value.
 
-For backward compatibility a new setting, `hibernate.id.generator.stored_last_used`, has been introduced that gives the opportunity to fall back to the old Hibernate behaviour.
+For backward compatibility, a new setting called `hibernate.id.generator.stored_last_used` was introduced, which gives you the opportunity to fall back to the old Hibernate behavior.
-Existing applications migrating to 5.3 and using @TableGenerator have to set `hibernate.id.generator.stored_last_used` to `false`.
+
+[NOTE]
+====
+Existing applications migrating to 5.3 and using the `@TableGenerator` have to set the `hibernate.id.generator.stored_last_used` configuration property to `false`.
+====
+
+=== Change in the `@TableGenerator` and `@SequenceGenerator` name scope
+
+In order to be compliant with the JPA specification, generators names are now considered global (e.g. https://hibernate.atlassian.net/browse/HHH-12157[HHH-12157]) .
+Configuring two generators, even if with different types but with the same name will now cause a `java.lang.IllegalArgumentException' to be thrown at boot time.
+
+For example, the following mappings are no longer valid:
+
+[source,java]
+----
+@Entity
+@TableGenerator(name = "ID_GENERATOR", ... )
+public class FirstEntity {
+    ....
+}
+
+@Entity
+@TableGenerator(name = "ID_GENERATOR", ... )
+public class SecondEntity {
+    ....
+}
+----
+
+or
+
+[source,java]
+----
+@Entity
+@TableGenerator(name = "ID_GENERATOR", ... )
+public class FirstEntity {
+    ....
+}
+
+@Entity
+@SequenceGenerator(name="ID_GENERATOR", ... )
+public class SecondEntity {
+    ....
+}
+----
+
+The solution is to make all generators unique so that there are no two generators with the same name.
 
 
 === Drop hibernate-infinispan module
 
-Support for using Infinispan as a Hibernate 2nd level cache provider has been moved to the Infinispan project so
+Support for using Infinispan as a Hibernate 2nd-level cache provider has been moved to the Infinispan project so
-the hibernate-infinispan module has been dropped.
+the `hibernate-infinispan` module has been dropped.
 
-A relocation pom pointing to `org.infinispan:infinispan-hibernate-cache` is now produced avoiding fro 5.3 the need to update any library dependency.
+A relocation pom which is pointing to `org.infinispan:infinispan-hibernate-cache` dependency is still generated,
+therefore, avoiding the need of updating any library dependency.
 
+[WARN]
+====
 The relocation pom may be dropped in a future release.
-
+====
-See also https://issues.jboss.org/browse/ISPN-8638.