Mention third-party dialects throughout the documentation

Author: yrodiere

dialects.adoc

@@ -4,7 +4,7 @@ A dialect is a class that provides information about the specifics of a database
 
 == Supported dialects
 
-Hibernate supports a wide range of dialects out of the box. The following is list of officially supported databases:
+Hibernate supports a wide range of dialects out of the box:
 
 * Apache Derby
 * Cockroach
@@ -29,6 +29,23 @@ but the support for these versions is not guaranteed.
 
 Apart from the Hibernate team supported dialects, there are also community dialects.
 
+== Third-party dialects
+
+Third-parties publish additional dialects for Hibernate ORM, providing their own support for more databases, or extended support beyond what is built in Hibernate ORM:
+
+* MongoDB: https://github.com/mongodb/mongo-hibernate/[MongoDB extension for Hibernate ORM]
+* Google Spanner: https://github.com/GoogleCloudPlatform/google-cloud-spanner-hibernate[Google Cloud Spanner Dialect for Hibernate ORM]
+
+[NOTE]
+====
+Third-party dialects are tested by their own authors,
+and may not be compatible with all versions of Hibernate ORM.
+
+1. Check the dialect's own documentation to know more about its compatibility constraints.
+The https://hibernate.org/orm/releases/#compatibility-matrix[compatibility matrix on the Hibernate website] may also be of help.
+2. Submit any question or bug reports about these dialects to the dialect's authors: the Hibernate team cannot help.
+====
+
 == Community dialects
 
 As of Hibernate 6.0, the Hibernate team decided to provide a clear way forward for community contributed dialects.

documentation/src/main/asciidoc/introduction/Configuration.adoc

@@ -68,10 +68,11 @@ driver for your database.
 | SQL Server                | `com.microsoft.sqlserver:mssql-jdbc:${version}`
 | Oracle                    | `com.oracle.database.jdbc:ojdbc11:${version}`
 | H2                        | `com.h2database:h2:{version}`
-| HSQLDB                    | `org.hsqldb:hsqldb:{version}`
+| MongoDB                   | The JDBC driver is bundled with the dialect mentioned in <<optional-dependencies>>
+| Google Spanner            | `com.google.cloud:google-cloud-spanner-jdbc:{version}`
 |===
 
-Where `{version}` is the latest version of the JDBC driver for your databse.
+Where `{version}` is the latest version of the JDBC driver for your database.
 
 [[optional-dependencies]]
 === Optional dependencies
@@ -118,6 +119,15 @@ and `com.github.ben-manes.caffeine:jcache`
 or `org.eclipse:yasson`
 | <<spatial,Hibernate Spatial>> | `org.hibernate.orm:hibernate-spatial`
 | <<envers,Envers>>, for auditing historical data | `org.hibernate.orm:hibernate-envers`
+| Community dialects | `org.hibernate.orm:hibernate-community-dialects`
+| Third-party dialects
+// TODO link to the /dialects/ documentation explaining what third-party dialects are?
+|
+https://github.com/mongodb/mongo-hibernate/[MongoDB]: `org.mongodb:mongodb-hibernate:{version}`
+
+https://github.com/GoogleCloudPlatform/google-cloud-spanner-hibernate[Google Spanner]: `com.google.cloud:google-cloud-spanner-hibernate-dialect:{version}`
+
+Where `{version}` is the version of the third-party dialect compatible with the version of Hibernate ORM you are using. See the dialect's own documentation for more information. The https://hibernate.org/orm/releases/#compatibility-matrix[compatibility matrix on the Hibernate website] may also be of help.
 |===
 
 You might also add the Hibernate {enhancer}[bytecode enhancer] to your
@@ -289,9 +299,10 @@ The properties you really do need to get started are these three:
 [IMPORTANT]
 // .You don't need `hibernate.dialect` anymore!
 ====
-In Hibernate 6, you don't need to specify `hibernate.dialect`.
+Starting with Hibernate 6, you don't need to specify `hibernate.dialect`.
 The correct Hibernate SQL `Dialect` will be determined for you automatically.
-The only reason to specify this property is if you're using a custom user-written `Dialect` class.
+// TODO link to the /dialects/ documentation explaining what community and third-party dialects are?
+The only reason to specify this property is if you're using a custom user-written or third-party `Dialect` class.
 
 Similarly, neither `hibernate.connection.driver_class` nor `jakarta.persistence.jdbc.driver` is needed when working with one of the supported databases.
 ====

documentation/src/main/asciidoc/quickstart/guides/obtaining.adoc

@@ -58,6 +58,7 @@ transitive dependencies based on the features being used or not.
 |hibernate-jcache| Integration with https://jcp.org/en/jsr/detail?id=107$$[JCache], allowing any compliant implementation as a second-level cache provider
 |hibernate-graalvm| Experimental extension to make it easier to compile applications as a https://www.graalvm.org/[GraalVM] native image
 |hibernate-micrometer| Integration with https://micrometer.io[Micrometer] metrics
+// TODO link to the /dialects/ documentation explaining what community dialects are?
 |hibernate-community-dialects| Additional community-supported SQL dialects
 |===
 
@@ -67,6 +68,26 @@ transitive dependencies based on the features being used or not.
 |hibernate-testing| A series of JUnit extensions for testing Hibernate ORM functionality
 |===
 
+[cols="40m,~"]
+.Third-party modules
+|===
+// Yes, this is a full row containing asciidoc containing an admonition. I don't know have a better idea to add an admonition between a table's title and its content.
+2+a|
+[NOTE]
+====
+Third-party modules are tested by their own authors,
+and may not be compatible with all versions of Hibernate ORM.
+
+1. Check the module's own documentation to know more about its compatibility constraints.
+The https://hibernate.org/orm/releases/#compatibility-matrix[compatibility matrix on the Hibernate website] may also be of help.
+2. Submit any question or bug reports about these dialects to the dialect's authors: the Hibernate team cannot help.
+
+// TODO link to the /dialects/ documentation explaining what third-party dialects are?
+====
+|`org.mongodb:mongodb-hibernate:{version}`| https://github.com/mongodb/mongo-hibernate/[MongoDB Extension for Hibernate ORM]
+|`com.google.cloud:google-cloud-spanner-hibernate-dialect:{version}`| https://github.com/GoogleCloudPlatform/google-cloud-spanner-hibernate[Google Cloud Spanner Dialect for Hibernate ORM]
+|===
+
 [[platform]]
 === Platform / BOM
 

documentation/src/main/asciidoc/userguide/chapters/jdbc/Database_Access.adoc

@@ -292,5 +292,8 @@ Hibernate abstracts over variations between dialects of SQL via the class `org.h
 - There's a subclass of `Dialect` for each supported relational database in the package `org.hibernate.dialect`.
 - Additional community-supported ``Dialect``s are available in the separate module `hibernate-community-dialects`.
 
-In Hibernate 6, it's no longer necessary to explicitly specify a dialect using the configuration property `hibernate.dialect`, and so setting that property is now discouraged.
-(An exception is the case of custom user-written ``Dialect``s.)
+Starting with Hibernate 6, it's no longer necessary to explicitly specify a dialect using the configuration property `hibernate.dialect`, and so setting that property is now discouraged.
+(An exception is the case of custom user-written ``Dialect``s.)
+
+// TODO link to the /dialects/ documentation
+// NOTE: For information about available dialects and compatible database versions, see << .... >>.

documentation/src/main/asciidoc/userguide/chapters/portability/Portability.adoc

@@ -14,8 +14,12 @@ Regardless of the exact scenario, the basic idea is that you want Hibernate to h
 
 The first line of portability for Hibernate is the dialect, which is a specialization of the `org.hibernate.dialect.Dialect` contract.
 A dialect encapsulates all the differences in how Hibernate must communicate with a particular database to accomplish some task like getting a sequence value or structuring a SELECT query.
+// TODO link to the /dialects/ documentation
 Hibernate bundles a wide range of dialects for many of the most popular databases.
-If you find that your particular database is not among them, it is not terribly difficult to write your own.
+If you find that your particular database is not among them,
+// TODO link to the /dialects/ documentation, "third-party" section
+you can check dialects implemented by third parties,
+and as a last resort it is not terribly difficult to write your own.
 
 [[portability-dialectresolver]]
 === Dialect resolution