diff --git a/migration-guide-5.0.adoc b/migration-guide-5.0.adoc
deleted file mode 100644
index 3cd1efaa20..0000000000
--- a/migration-guide-5.0.adoc
+++ /dev/null
@@ -1,28 +0,0 @@
-= 5.0 Migration Guide
-:toc:
-
-This guide discusses migration from Hibernate ORM version 4.3 to version 5.0.  For migration from
-earlier versions, see any other pertinent migration guides as well.
-
-* Re-purposing of Configuration.  Configuration, historically, allowed users to iteratively add
-settings and mappings in any order and to query the state of settings and mapping information in the middle
-of that process.  Which meant that building the mapping information could not effectively rely on any settings
-being available.  This lead to many limitations and problems.  Quite a few methods have been removed from
-Configuration.  todo : topical guide on bootstrapping, reference that here.
-
-* Migrated `org.hibernate.metamodel.spi.TypeContributor` and `org.hibernate.metamodel.spi.TypeContributions`
-to `org.hibernate.boot.model.TypeContributor` and `org.hibernate.boot.model.TypeContributions`
-
-* Naming strategies - discuss split.
-
-* implicit column names, add to strategy?  Currently these are handled "specially":
-** PrimaryKeyJoinColumn
-*** joined-subclass key column(s) - JPA defaults
-*** secondary table key column(s) - JPA defaults
-*** one-to-one key column(s) - JPA defaults
-** entity simple identifier column - JPA defaults
-** entity version - currently uses #determineAttributeColumnName
-** collection-id column name - currently hard-coded as "id"
-** list-index column name - currently hard-coded as "idx"
-
-* hibernate.jdbc.batch_versioned_data default value is true, Oracle dialects set this property to false except for Oracle12cDialect
\ No newline at end of file
diff --git a/migration-guide.adoc b/migration-guide.adoc
new file mode 100644
index 0000000000..e6b93d99f2
--- /dev/null
+++ b/migration-guide.adoc
@@ -0,0 +1,118 @@
+= 5.0 Migration Guide
+:toc:
+
+This guide discusses migration from Hibernate ORM version 4.3 to version 5.0.  For migration from
+earlier versions, see any other pertinent migration guides as well.
+
+== Re-purposing of Configuration
+
+Configuration, historically, allowed users to iteratively add settings and mappings in any order and to query the
+state of settings and mapping information in the middle of that process.  Which meant that building the mapping
+information could not effectively rely on any settings being available.  This lead to many limitations and problems.
+
+Quite a few methods have been removed from Configuration.  Be sure to see the User Guide chapter on bootstrapping for
+details.  For applications that integrate with Hibernate via one or more APIs, this change might effect your
+integrations as well.
+
+
+== Short-naming
+
+In an effort to insulate applications from refactoring efforts, Hibernate has begun to recognize "short name" values for
+certain configuration settings.  These are discussed in detail in the User Guide in the pertinent sections.
+
+Where available, we highly recommend using the short name for a setting value.
+
+
+== Transactions
+
+The transaction SPI underwent a major redesign as part of 5.0 as well.  From a user perspective this generally
+only comes into view in terms of configuration.  Previously applications would work with the different backend
+transaction stratagies directly via the `org.hibernate.Transaction` API.  In 5.0 a level of indirection has been
+added here.  The API implementation of `org.hibernate.Transaction` is always the same now.  On the backend, the
+`org.hibernate.Transaction` impl talks to a `org.hibernate.resource.transaction.TransactionCoordinator` which represents
+the "transactional context" for a given Session according to the backend transaction strategy.  Users generally do not
+need to care about the distinction.
+
+The change is noted here because it might affect your bootstrap configuration.  Whereas previously applications would
+specify `hibernate.transaction.factory_class` and refer to a `org.hibernate.engine.transaction.spi.TransactionFactory` FQN,
+with 5.0 the new contract is `org.hibernate.resource.transaction.TransactionCoordinatorBuilder` and is specified using the
+`hibernate.transaction.coordinator_class` setting.  See `org.hibernate.cfg.AvailableSettings.TRANSACTION_COORDINATOR_STRATEGY`
+JavaDocs for additional details.
+
+The following short-names are recognized:
+`jdbc`::(the default) says to use JDBC-based transactions (`org.hibernate.resource.transaction.backend.jdbc.internal.JdbcResourceLocalTransactionCoordinatorImpl`)
+`jta`::says to use JTA-based transactions (`org.hibernate.resource.transaction.backend.jta.internal.JtaTransactionCoordinatorImpl`)
+
+See the User Guide for additional details.
+
+
+== Type handling
+
+* Migrated `org.hibernate.metamodel.spi.TypeContributor` and `org.hibernate.metamodel.spi.TypeContributions`
+	to `org.hibernate.boot.model.TypeContributor` and `org.hibernate.boot.model.TypeContributions`
+* Built-in `org.hibernate.type.descriptor.sql.SqlTypeDescriptor` implementations no longer auto-register themselves
+    with `org.hibernate.type.descriptor.sql.SqlTypeDescriptorRegistry`.  Applications using custom SqlTypeDescriptor
+    implementations extending the built-in ones and relying on that behavior should be updated to call
+    `SqlTypeDescriptorRegistry#addDescriptor` themselves.
+* The JDBC type for "big_integer" (org.hibernate.type.BigIntegerType) properties has changed from
+    java.sql.Types,NUMERIC to java.sql.Types.BIGINT.
+* For ids defined as UUID with generation, for some databases it is required to explicitly set the `@Column( length=16 )`
+    in order to generate BINARY(16) so that comparisons properly work.
+* For EnumType mappings defined in hbm.xml where the user wants name-mapping (`javax.persistence.EnumType#STRING`)
+    the configuration must explicitly state that using either the `useNamed` (true) setting or by specifying the `type`
+    setting set to the value 12 (VARCHAR JDBC type code).
+
+
+== Naming strategies
+
+Historically Hibernate provided just a singular contract for applying a "naming strategy". Starting in 5.0 this has
+been split into 2 distinct contracts:
+* `ImplicitNamingStrategy` - is used whenever a table or column is not explicitly named to determine the name to use.
+* `PhysicalNamingStrategy` - is used to convert a "logical name" (either implicit or explicit) name of a table or column
+into a physical name (e.g. following corporate naming guidelines)
+
+
+== Changed setting defaults
+
+* Default value for `hibernate.id.new_generator_mappings` setting changed to true for 5.0.  See
+    `org.hibernate.cfg.AvailableSettings#USE_NEW_ID_GENERATOR_MAPPINGS` javadocs.
+* The default ImplicitNamingStrategy (`hibernate.implicit_naming_strategy`) has changed to the JPA-compliant one.  See
+    `org.hibernate.cfg.AvailableSettings.IMPLICIT_NAMING_STRATEGY` javadocs for details.  If you experience problems
+    migrating dues to implicit table or column names you may want to specify the legacy strategy
+    (`legacy-hbm` \ `org.hibernate.boot.model.naming.ImplicitNamingStrategyLegacyHbmImpl`).
+* `hibernate.jdbc.batch_versioned_data` default value is now true; Oracle dialects set this property to false,
+except for Oracle12cDialect
+
+
+== Misc
+
+* `cfg.xml` files are again fully parsed and integrated (events, security, etc)
+* properties loaded from `cfg.xml` through EntityManagerFactory did not previously prefix names with "hibernate." this is now made consistent.
+* `Configuration` is  no longer `Serializable`
+* `org.hibernate.dialect.Dialect.getQuerySequencesString` expected to retrieve catalog, schema, and increment values as well
+* removed AuditConfiguration in preference for new `org.hibernate.envers.boot.internal.EnversService`
+* changed AuditStrategy method parameters from (removed) AuditConfiguration to (new) EnversService
+* Moving `org.hibernate.hql.spi.MultiTableBulkIdStrategy` and friends to new `org.hibernate.hql.spi.id` package
+    and sub-packages
+* Complete redesign of "property access" contracts
+* Valid `hibernate.cache.default_cache_concurrency_strategy` setting values are now defined via
+    `org.hibernate.cache.spi.access.AccessType#getExternalName` rather than the `org.hibernate.cache.spi.access.AccessType`
+    enum names; this is more consistent with other Hibernate settings
+
+
+== Deprecations
+
+* Removed the deprecated `org.hibernate.cfg.AnnotationConfiguration`
+* Removed deprecated `org.hibernate.id.TableGenerator` id-generator
+* Removed deprecated `org.hibernate.id.TableHiLoGenerator` (hilo) id-generator
+* Deprecated `org.hibernate.id.SequenceGenerator` and its subclasses
+* Added a new dedicated "deprecation logger" to consolidate logging for deprecated uses.
+
+== Changed/Moved contracts
+
+* `org.hibernate.integrator.spi.Integrator` contract changed to account for bootstrap redesign
+* Extracted `org.hibernate.engine.jdbc.env.spi.JdbcEnvironment` from `JdbcServices`;
+	created `org.hibernate.engine.jdbc.env` package and moved a few contracts there.
+* Introduction of `org.hibernate.boot.model.relational.ExportableProducer` which will effect any
+	`org.hibernate.id.PersistentIdentifierGenerator` implementations
+* Changed to signature of `org.hibernate.id.Configurable` to accept `ServiceRegistry` rather than just `Dialect`
diff --git a/working-5.0-migration-guide.md b/working-5.0-migration-guide.md
deleted file mode 100644
index fa0472b9c6..0000000000
--- a/working-5.0-migration-guide.md
+++ /dev/null
@@ -1,97 +0,0 @@
-Working list of changes for 5.0
-===================================
-
-* Switch from Configuration to ServiceRegistry+Metadata for SessionFactory building
-* `org.hibernate.hql.spi.MultiTableBulkIdStrategy#prepare` contract has been changed to account for Metadata
-* (proposed) `org.hibernate.persister.spi.PersisterFactory` contract, specifically building CollectionPersisters)
-  has been changed to account for Metadata
-* extract `org.hibernate.engine.jdbc.env.spi.JdbcEnvironment` from `JdbcServices`; create
-  `org.hibernate.engine.jdbc.env` package and moved a few contracts there.
-* Introduction of `org.hibernate.boot.model.relational.ExportableProducer` which will effect any
- `org.hibernate.id.PersistentIdentifierGenerator` implementations
-* Change to signature of `org.hibernate.id.Configurable` to accept `ServiceRegistry` rather than just `Dialect`
-* Removed deprecated `org.hibernate.id.TableGenerator` id-generator
-* Removed deprecated `org.hibernate.id.TableHiLoGenerator` (hilo) id-generator
-* Deprecated `org.hibernate.id.SequenceGenerator` and its subclasses
-* cfg.xml files are again fully parsed and integrated (events, security, etc)
-* Removed the deprecated `org.hibernate.cfg.AnnotationConfiguration`
-* `Integrator` contract
-* `Configuration` is  no longer `Serializable`
-* `org.hibernate.dialect.Dialect.getQuerySequencesString` expected to retrieve catalog, schema, and increment values as well
-* properties loaded from cfg.xml through EMF did not previously prefix names with "hibernate." this is now made consistent.
-* removed AuditConfiguration in preference for new `org.hibernate.envers.boot.internal.EnversService`
-* changed AuditStrategy method parameters from (removed) AuditConfiguration to (new) EnversService
-* Built-in `org.hibernate.type.descriptor.sql.SqlTypeDescriptor` implementations no longer auto-register themselves
-    with `org.hibernate.type.descriptor.sql.SqlTypeDescriptorRegistry`.  Applications using custom SqlTypeDescriptor
-    implementations extending the built-in ones and relying on that behavior should be updated to call
-    `SqlTypeDescriptorRegistry#addDescriptor` themselves.
-* The JDBC type for "big_integer" (org.hibernate.type.BigIntegerType) properties has changed from 
-    java.sql.Types,NUMERIC to java.sql.Types.BIGINT.
-* Moving `org.hibernate.hql.spi.MultiTableBulkIdStrategy` and friends to new `org.hibernate.hql.spi.id` package
-    and sub-packages
-* Changes to "property access" contracts, including 
-* Valid `hibernate.cache.default_cache_concurrency_strategy` setting values are now defined via
-    `org.hibernate.cache.spi.access.AccessType#getExternalName` rather than the `org.hibernate.cache.spi.access.AccessType`
-    enum names; this is more consistent with other Hibernate settings
-* For ids defined as UUID with generation, for some databases it is required to explicitly set the `@Column( length=16 )`
-    in order to generate BINARY(16) so that comparisons properly work.
-* For EnumType mappings defined in hbm.xml where the user wants name-mapping (`javax.persistence.EnumType#STRING`) 
-    the configuration must explicitly state that using either the `useNamed` (true) setting or by specifying the `type`
-    setting set to the value 12 (VARCHAR JDBC type code).
-* Default value for `hibernate.id.new_generator_mappings` setting changed to true for 5.0.  See 
-    `org.hibernate.cfg.AvailableSettings#USE_NEW_ID_GENERATOR_MAPPINGS` javadocs.
-* The default ImplicitNamingStrategy (`hibernate.implicit_naming_strategy`) has changed to the JPA-compliant one.  See 
-    `org.hibernate.cfg.AvailableSettings.IMPLICIT_NAMING_STRATEGY` javadocs for details.
-    
-
-TODOs
-=====
-* Still need to go back and make all "persistent id generators" to properly implement ExportableProducer
-* Add a setting to "consistently apply" naming strategies.  E.g. use the "join column" methods from hbm.xml binding.
-* Along with this ^^ consistency setting, split the implicit naming strategy for join columns into multiple methods - one for each usage:
-   * many-to-one
-   * one-to-one
-   * etc
-
-
-Blog items
-==========
-* New bootstrapping API - better determinism, better integration
-* Java 8 Support (though still compatible with Java 6).
-* hibernate-spatial
-* Ability to handle additional Java types for id attributes marked as `GenerationType#AUTO`.  Built-in support
-    for Number and UUID.  Expandable via new `org.hibernate.boot.model.IdGeneratorStrategyInterpreter` extension
-* Expanded support for AttributeConverters.
-    * fully supported for non-`@Enumerated` enum values
-    * applicable in conjunction with `@Nationalized` support
-    * called to handle null values
-    * settable in hbm.xml by using `type="converter:fully.qualified.AttributeConverterName"`
-    * integrated with hibernate-envers
-    * collection values, map keys
-* scanning support for non-JPA usage
-* naming strategy split.  default is now to be jpa-compliant
-* OSGi improvements, Karaf feature file published
-
-
-Proposals for discussion
-========================
-* Currently there is a "post-binding" hook to allow validation of the bound model (PersistentClass,
-Property, Value, etc).  However, the top-level entry points are currently the only possible place
-(per contract) to throw exceptions when a validation fails".  I'd like to instead consider a pattern
-where each level is asked to validate itself.  Given the current model, however, this is unfortunately
-not a win-win situation.  `org.hibernate.boot.model.source.internal.hbm.ModelBinder#createManyToOneAttribute`
-illustrates one such use case where this would be worthwhile, and also can illustrate how pushing the
-validation (and exception throwing down) can be less than stellar given the current model.  In the process
-of binding a many-to-one, we need to validate that any many-to-one that defines "delete-orphan" cascading
-is a "logical one-to-one".  There are 2 ways a many-to-one can be marked as a "logical one-to-one"; first
-is at the `<many-to-one/>` level; the other is through a singular `<column/>` that is marked as unique.
-Occasionally the binding of the column(s) of a many-to-one need to be delayed until a second pass, which
-means that sometimes we cannot perform this check immediately from the `#createManyToOneAttribute` method.
-What would be ideal would be to check this after all binding is complete.  In current code, this could be
-either an additional SecondPass or done in a `ManyToOne#isValid` override of `SimpleValue#isValid`.  The
-`ManyToOne#isValid` approach illustrates the conundrum... In the `ManyToOne#isValid` call we know the real
-reason the validation failed (non-unique many-to-one marked for orphan delete) but not the property name/path.
-Simply returning false from `ManyToOne#isValid` would instead lead to a misleading exception message, which
-would at least have the proper context to know the property name/path.
-* Consider an additional "naming strategy contract" specifically for logical naming.  This would be non-pluggable, and
-would be the thing that generates the names we use to cross-reference and locate tables, columns, etc.