migration guide structure

Author: sebersole

migration-guide.adoc

@@ -256,16 +256,24 @@ Relatedly, `org.hibernate.annotations.CascadeType#SAVE_UPDATE` has been removed
 
 `Session#delete` methods has been removed in favor of `Session#remove` (via `EntityManager`).  Relatedly, `org.hibernate.annotations.CascadeType#DELETE` was removed in favor of `org.hibernate.annotations.CascadeType#REMOVE`
 
-[[metamodel]]
-=== Metamodel
+[[load-fetch-graphs]]
+=== org.hibernate.graph Package
 
-`org.hibernate.Metamodel` has been removed in favor of `org.hibernate.metamodel.model.domain.JpaMetamodel`
+The `EntityGraph` API was enhanced in JPA 3.2, and made much more useful.
+The incubating package `org.hibernate.graph` contains extensions to that API, which have been significantly impacted by the migration to JPA 3.2, and by the addition of new functionality.
+Furthermore, some legacy operations were declared with incorrect generic type signatures (by both JPA, and by Hibernate).
 
+This package has been significantly re-engineered, and the impact of this effort includes:
 
-[[session-by-natural-id]]
-=== Session#byNaturalId
+- some breaking changes to type signatures, and
+- a number of deprecations of legacy operations which are now covered by JPA.
+
+Also, a key subgraph now always refers to a `Map` key, and never to an entity id.
 
-Both `NaturalIdLoadAccess#using(Map)` and `NaturalIdMultiLoadAccess#compoundValue()` have been removed in favor of `Map#of()`
+We encourage migration to the use of the new JPA-standard operations.
+
+Or, alternatively, when building graphs, consider Hibernate's support for
+textual link:{user-guide-url}#fetching-strategies-dynamic-fetching-entity-graph-parsing[graph parsing].  See also <<NamedEntityGraph>>.
 
 
 [[removal-annotations]]
@@ -314,7 +322,9 @@ The effect can also often be mitigated using Hibernate's bytecode-based laziness
 [[misc-api]]
 === Miscellaneous
 
+* Removed `org.hibernate.Metamodel` in favor of `org.hibernate.metamodel.model.domain.JpaMetamodel`
 * Removed `SqmQualifiedJoin` - all joins are qualified.
+* Both `NaturalIdLoadAccess#using(Map)` and `NaturalIdMultiLoadAccess#compoundValue()` have been removed in favor of `Map#of()`
 * Removed `Session.LockRequest` - use `LockOptions` instead
 
 
@@ -451,21 +461,8 @@ This includes auto-applied converters.
 To suppress the error for an auto-applied converter, use `@Convert(disableConversion=true)`.
 
 
-[[load-fetch-graphs]]
-=== org.hibernate.graph Package
-
-The `EntityGraph` API was enhanced in JPA 3.2, and made much more useful.
-The incubating package `org.hibernate.graph` contains extensions to that API, which have been significantly impacted by the migration to JPA 3.2, and by the addition of new functionality.
-Furthermore, some legacy operations were declared with incorrect generic type signatures (by both JPA, and by Hibernate).
-
-This package has been significantly re-engineered, and the impact of this effort includes:
-
-- some breaking changes to type signatures, and
-- a number of deprecations of legacy operations which are now covered by JPA.
 
-Also, a key subgraph now always refers to a `Map` key, and never to an entity id.
 
-We encourage migration to the use of the new JPA-standard operations.
 
 [[create-query]]
 === Query with Implicit SELECT and No Explicit Result Type