HHH-10812 Adding documentation

documentation/src/main/asciidoc/topical/index.adoc

@@ -14,6 +14,7 @@ NOTE: This is still very much a work in progress. <<helping,Help>> is definitely
 ** For (semi-deprecated) bootstrapping of a SessionFactory using the legacy Configuration approach, see the <<bootstrap/LegacyBootstrapping.adoc#,Legacy Bootstrapping Guide>>
 * For information on generated (non-identifier) values, see the <<generated/GeneratedValues.adoc#,Generated Values Guide>>
 * For information on logging, see <<logging/Logging.adoc#,Logging Guide>>
+* For information on how to use the latest version of Hibernate ORM on WildFly, see <<wildfly/Wildfly.adoc#,Using Hibernate ORM on Wildfly>>
 * Others coming soon
 
 == Tooling

documentation/src/main/asciidoc/topical/wildfly/Wildfly.adoc

@@ -0,0 +1,54 @@
+= Updating Hibernate ORM within WildFly
+
+The http://wildfly.org/[WildFly application server] comes with Hibernate as the default JPA provider out of the box.
+This means that you don't need to package Hibernate ORM with the applications you deploy on WildFly,
+instead the application server will automatically enable Hibernate support if it detects that your application works with JPA/Hibernate.
+
+There may be times though where a newer version of Hibernate ORM is available than the one coming with a given WildFly release.
+For that case the Hibernate ORM project provides a ZIP file containing the required modules to update a WildFly installation to newer versions.
+The module ZIP file is available from SourceForge and BinTray, alike the ZIP/TAR.GZ distributions (TODO: Add link).
+As of Hibernate ORM 5.1.1, a ZIP file for upgrading WildFly 10 to that Hibernate version (from 5.0.x) is provided.
+The general goal is to provide a ZIP file for bringing new versions of Hibernate ORM to the WildFly version current at the time of the Hibernate release.
+
+Once downloaded, extract the contents of the ZIP file into the _modules_ directory of your WildFly installation
+(shut down the application server before, should it be running).
+Note that the Hibernate ORM modules coming with WildFly will remain untouched,
+i.e. you can switch between the original version and the new version from the ZIP file as needed as a matter of configuration.
+
+The module system of the application server uses what's called "slots" to differentiate between several versions of one module.
+By default, slot "main" of the Hibernate ORM modules will be used to provide JPA support for given deployments (representing the Hibernate version coming with WildFly itself).
+In order to use another slot, specify the following two property in the _persistence.xml_ file of your application:
+
+[[wildfly-using-custom-hibernate-orm-version]]
+.Using a specific version of Hibernate ORM
+====
+[source, XML]
+----
+<persistence xmlns="http://xmlns.jcp.org/xml/ns/persistence"
+    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+    xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/persistence
+    http://xmlns.jcp.org/xml/ns/persistence/persistence_2_1.xsd"
+    version="2.1" >
+
+    <persistence-unit name="examplePu" transaction-type="JTA">
+
+        <!-- ... -->
+
+        <properties>
+            <property name="jboss.as.jpa.providerModule" value="org.hibernate:<%VERSION%>"/>
+        </properties>
+
+        <!-- ... -->
+
+    </persistence-unit>
+</persistence>
+----
+====
+
+For `<%VERSION%>` specify the version of the module ZIP you downloaded, e.g. `5.1.1.Final`.
+Alternatively you can specify just the minor version, e.g. `5.1`.
+That way you can update your WildFly server with further micro updates of the same Hibernate ORM release family as they are released,
+without having to adapt your _persistence.xml_ upon each micro update.
+Note that you can have several micro updates of the same release family next to each other within a WildFly instance
+and switch between them by means of the properties shown above.
+If you are specifying just the minor version as module slot, the modules from the ZIP file you unpacked last will be used.