HHH-12773 : Document org.hibernate.Query.getHibernateFirstResult(), setHibernateFirstResult(), getHibernateMaxResults(), setHibernateMaxResults() in migration guide

migration-guide.adoc

@@ -75,6 +75,39 @@ did not implement "correctly" anyway
 The change for HHH-11356 required changes in its consumers.  One such consumer is the Hibernate
 Statistics system....
 
+=== Native (non-JPA) Pagination changes
+
+When hibernate-entitymanager module was merged into hibernate-core in Hibernate ORM 5.2, the contracts for the 
+following pre-existing `org.hibernate.Query` methods were changed to be specified by JPA `javax.persistence.Query` 
+methods: `getFirstResult()`, `setFirstResult(int)`, `getMaxResults()`, and `setMaxResults()`.
+
+In 5.3.2, the following methods were temporarily added to
+http://docs.jboss.org/hibernate/orm/5.3/javadocs/org/hibernate/Query.html[`org.hibernate.Query`] to make it
+easier to migrate native applications from Hibernate ORM 5.1 to 5.3, and maintain 5.1 pagination behavior:
+
+* http://docs.jboss.org/hibernate/orm/5.3/javadocs/org/hibernate/Query.html#setHibernateFirstResult-int-[`setHibernateFirstResult(int)`] 
+behaves the same as the 5.1 version of `setFirstResult()`, with a small difference -- calling 
+`setHibernateFirstResult(int)` with a negative value will result in `getHibernateFirstResult()` returning 0, instead 
+of the negative value. Note that this behavior differs from JPA in that `javax.persistence.Query.setFirstResult(int)` 
+throws `IllegalArgumentException` when called with a negative value.
+* http://docs.jboss.org/hibernate/orm/5.3/javadocs/org/hibernate/Query.html#getHibernateFirstResult--[`getHibernateFirstResult()`] 
+behaves the same as the 5.1 version of `getFirstResult()`, except for the difference mentioned above when `setHibernateFirstResult(int)` is called with a negative number. This method returns `null` if no value was set 
+via `setHibernateFirstResult(int)` (or `setFirstResult(int)`). Note that this behavior differs from JPA in that
+`javax.persistence.Query.getFirstResult()` returns 0 when uninitialized.
+* http://docs.jboss.org/hibernate/orm/5.3/javadocs/org/hibernate/Query.html#setHibernateMaxResults-int-[`setHibernateMaxResults`] 
+behaves the same as the 5.1 version of `setMaxResults()`; setting a value less than or equal to 0 is 
+considered uninitialized, resulting in *no limit* on the number of results. Note that this behavior differs 
+from JPA `javax.persistence.Query.setMaxResults(int)`, which, when called with a negative value, 
+throws `IllegalArgumentException`, and when called with a value of 0, indicates that the query should return 
+*no results*.
+* http://docs.jboss.org/hibernate/orm/5.3/javadocs/org/hibernate/Query.html#getHibernateMaxResults--[`getHibernateMaxResults`]
+behaves the same as the 5.1 version of `#getMaxResults`. This method returns `null` if uninitialized or
+a value less than or equal to 0 was set via `setHibernateMaxResults(int)` (or `setMaxResults(int)`).
+Note that this behavior differs from JPA in that `javax.persistence.Query.getMaxResults() returns 
+`Integer.MAX_VALUE` when uninitialized.
+
+These methods are deprecated, and will be removed in a future version. To be portable with future Hibernate 
+versions, applications should be changed to use the JPA methods.
 
 === Drop hibernate-infinispan module
 
@@ -139,7 +172,6 @@ Existing applications migrating to 5.3 with classes extending `org.hibernate.jpa
 The original driving force behind these series of changes is an effort to be as proactive as possible
 about designing compatibility between 5.3 and 6.0.
 
-
 ==== Type system changes
 
-Use of NavigableRole, back-ported from 6.0 rather than plain String
+Use of NavigableRole, back-ported from 6.0 rather than plain String