HHH-17259 Add a "compatibility" section to the user guide

documentation/documentation.gradle

@@ -248,7 +248,10 @@ asciidoctorj {
 			experimental: true,
 			'source-highlighter': 'rouge',
 			majorMinorVersion: rootProject.ormVersion.family,
-			fullVersion: rootProject.ormVersion.fullName
+			fullVersion: rootProject.ormVersion.fullName,
+			javaCompatibleVersions: jdks.versions.compatible.get(),
+			jakartaJpaVersion: rootProject.jakartaJpaVersion,
+			jdbcVersion: jdks.versions.jdbc.get()
 
 	options logDocuments: true
 }
@@ -581,7 +584,7 @@ def renderUserGuideHtmlTask = tasks.register( 'renderUserGuideHtml', Asciidoctor
 	inputs.property "hibernate-version", project.ormVersion
 	inputs.file( generateSettingsDocTask.get().outputFile )
 
-	dependsOn generateSettingsDocTask
+	dependsOn generateSettingsDocTask, generateDialectTableReport
 
 	sourceDir = file( 'src/main/asciidoc/userguide' )
 	sources {
@@ -592,7 +595,8 @@ def renderUserGuideHtmlTask = tasks.register( 'renderUserGuideHtml', Asciidoctor
 	attributes linkcss: true,
 			   stylesheet: "css/hibernate.css",
 			   docinfo: 'private',
-			   jpaJavadocUrlPrefix: "https://javaee.github.io/javaee-spec/javadocs/javax/persistence/"
+			   jpaJavadocUrlPrefix: "https://javaee.github.io/javaee-spec/javadocs/javax/persistence/",
+			   'generated-report-dir': layout.buildDirectory.dir( 'orm/generated' )
 
 	resources {
 		from( 'src/main/asciidoc/userguide/' ) {

documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc

@@ -14,6 +14,7 @@ include::Preface.adoc[]
 
 :numbered:
 
+include::chapters/compatibility/Compatibility.adoc[]
 include::chapters/architecture/Architecture.adoc[]
 include::chapters/domain/DomainModel.adoc[]
 include::chapters/bootstrap/Bootstrap.adoc[]

documentation/src/main/asciidoc/userguide/chapters/compatibility/Compatibility.adoc

@@ -0,0 +1,76 @@
+[[compatibility]]
+== Compatibility
+
+[[compatibility-dependencies]]
+=== [[system-requirements]] Dependencies
+
+Hibernate {fullVersion} requires the following dependencies (among others):
+
+.Compatible versions of dependencies
+[cols="h,^1", stripes=none]
+|===============
+| h|Version
+|Java Runtime
+|{javaCompatibleVersions}
+|https://jakarta.ee/specifications/persistence/[Jakarta Persistence]
+|{jakartaJpaVersion}
+|JDBC (bundled with the Java Runtime)
+|{jdbcVersion}
+|===============
+
+[TIP]
+====
+Find more information for all versions of Hibernate on our
+https://hibernate.org/orm/releases/#compatibility-matrix[compatibility matrix].
+
+The https://hibernate.org/community/compatibility-policy/[compatibility policy] may also be of interest.
+====
+
+If you get Hibernate from Maven Central, it is recommended to import Hibernate Platform
+as part of your dependency management to keep all its artifact versions aligned.
+
+Gradle::
+[source, groovy, subs="+attributes"]
+----
+dependencies {
+  implementation platform "org.hibernate.orm:hibernate-platform:{fullVersion}"
+
+  // use the versions from the platform
+  implementation "org.hibernate.orm:hibernate-core"
+  implementation "jakarta.transaction:jakarta.transaction-api"
+}
+----
+Maven::
+[source, XML, subs="+attributes"]
+----
+<dependencyManagement>
+    <dependencies>
+        <dependency>
+            <groupId>org.hibernate.search</groupId>
+            <artifactId>hibernate-platform</artifactId>
+            <version>{fullVersion}</version>
+            <type>pom</type>
+            <scope>import</scope>
+        </dependency>
+    </dependencies>
+</dependencyManagement>
+<!-- use the versions from the platform -->
+<dependencies>
+    <dependency>
+        <groupId>org.hibernate.orm</groupId>
+        <artifactId>hibernate-core</artifactId>
+    </dependency>
+    <dependency>
+        <groupId>jakarta.transaction</groupId>
+        <artifactId>jakarta.transaction-api</artifactId>
+    </dependency>
+</dependencies>
+----
+
+[[compatibility-database]]
+=== Database
+
+Hibernate {fullVersion} is compatible with the following database versions,
+provided you use the corresponding <<database-dialect,dialects>>:
+
+include::{generated-report-dir}/dialect/dialect-table.adoc[]

local-build-plugins/src/main/java/org/hibernate/orm/post/DialectReportTask.java

@@ -22,6 +22,8 @@ import org.gradle.api.Project;
 import org.gradle.api.file.RegularFile;
 import org.gradle.api.provider.Property;
 import org.gradle.api.provider.Provider;
+import org.gradle.api.tasks.Input;
+import org.gradle.api.tasks.OutputFile;
 import org.gradle.api.tasks.SourceSet;
 import org.gradle.api.tasks.SourceSetContainer;
 import org.gradle.api.tasks.TaskAction;
@@ -31,8 +33,6 @@ import org.hibernate.orm.env.HibernateVersion;
 import org.jboss.jandex.ClassInfo;
 import org.jboss.jandex.Index;
 
-import static org.hibernate.orm.post.ReportGenerationPlugin.TASK_GROUP_NAME;
-
 /**
  * Generates a report on Dialect information
  *
@@ -40,11 +40,23 @@ import static org.hibernate.orm.post.ReportGenerationPlugin.TASK_GROUP_NAME;
  */
 public abstract class DialectReportTask extends AbstractJandexAwareTask {
 	private final Property<RegularFile> reportFile;
+	private final Property<Boolean> generateHeading;
 
 	public DialectReportTask() {
 		setDescription( "Generates a report of the supported Dialects" );
 		reportFile = getProject().getObjects().fileProperty();
 		reportFile.convention( getProject().getLayout().getBuildDirectory().file( "orm/generated/dialect/dialect.adoc" ) );
+		generateHeading = getProject().getObjects().property( Boolean.class ).convention( true );
+	}
+
+	@OutputFile
+	public Property<RegularFile> getReportFile() {
+		return reportFile;
+	}
+
+	@Input
+	public Property<Boolean> getGenerateHeading() {
+		return generateHeading;
 	}
 
 	@Override
@@ -116,11 +128,14 @@ public abstract class DialectReportTask extends AbstractJandexAwareTask {
 
 	private void writeDialectReportHeader(OutputStreamWriter fileWriter) {
 		try {
-			fileWriter.write( "= Supported Dialects\n\n" );
-			fileWriter.write( "Supported Dialects along with the minimum supported version of the underlying database.\n\n\n" );
+			if ( this.generateHeading.get() ) {
+				fileWriter.write( "= Supported Dialects\n\n" );
+				fileWriter.write(
+						"Supported Dialects along with the minimum supported version of the underlying database.\n\n\n" );
 
-			HibernateVersion ormVersion = (HibernateVersion) getProject().getRootProject().getExtensions().getByName( "ormVersion" );
-			fileWriter.write( "NOTE: Hibernate version " + ormVersion.getFamily() + "\n\n" );
+				HibernateVersion ormVersion = (HibernateVersion) getProject().getRootProject().getExtensions().getByName( "ormVersion" );
+				fileWriter.write( "NOTE: Hibernate version " + ormVersion.getFamily() + "\n\n" );
+			}
 
 			fileWriter.write( "[cols=\"a,a\", options=\"header\"]\n" );
 			fileWriter.write( "|===\n" );

local-build-plugins/src/main/java/org/hibernate/orm/post/ReportGenerationPlugin.java

@@ -63,6 +63,16 @@ public class ReportGenerationPlugin implements Plugin<Project> {
 				(task) -> task.dependsOn( indexerTask )
 		);
 
+		final TaskProvider<DialectReportTask> dialectTableTask = project.getTasks().register(
+				"generateDialectTableReport",
+				DialectReportTask.class,
+				(task) -> {
+					task.dependsOn( indexerTask );
+					task.setProperty( "generateHeading", false );
+					task.setProperty( "reportFile", project.getLayout().getBuildDirectory().file( "orm/generated/dialect/dialect-table.adoc" ) );
+				}
+		);
+
 		final Task groupingTask = project.getTasks().maybeCreate( "generateReports" );
 		groupingTask.setGroup( TASK_GROUP_NAME );
 		groupingTask.dependsOn( indexerTask );
@@ -71,5 +81,6 @@ public class ReportGenerationPlugin implements Plugin<Project> {
 		groupingTask.dependsOn( internalsTask );
 		groupingTask.dependsOn( loggingTask );
 		groupingTask.dependsOn( dialectTask );
+		groupingTask.dependsOn( dialectTableTask );
 	}
 }

settings.gradle

@@ -53,6 +53,8 @@ dependencyResolutionManagement {
     versionCatalogs {
         jdks {
             version "baseline", "11"
+            version "compatible", "11, 17 or 21"
+            version "jdbc", "4.2" // Bundled with JDK 11
 
             // Gradle does bytecode transformation on tests.
             // You can't use bytecode higher than what Gradle supports, even with toolchains.