HHH-12157 - Add migration guide notes

migration-guide.adoc

@@ -168,8 +168,50 @@ update test_entity
 set clobfield = lo_from_bytea( 0, cast( clobfield as bytea ) ),
     firstlobfield = lo_from_bytea( 0, cast( firstlobfield as bytea ) ),
     secondlobfield = lo_from_bytea( 0, cast( secondlobfield as bytea ) )
+
 ----
 
+=== Change in the `@TableGenerator` and `@SequenceGenerator` name scope
+
+In order to be compliant with the JPA specification, from 5.2.13 generators names are 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.
+
 == Misc
 
 * QueryCacheFactory contract changed