HHH-19889 Mention third-party dialects throughout the documentation

Author: yrodiere

documentation/src/main/asciidoc/dialect/dialect.adoc

@@ -24,6 +24,33 @@ Below is a list of supported dialects and the minimum required version of the da
 
 include::{generated-report-dir}/dialect/dialect-table.adoc[]
 
+[[third-party-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.
+
+These dialects are not directly supported by the Hibernate team:
+
+* The Hibernate ORM CI does not run any test against these dialects, the dialect's authors have their own test suite.
+* The Hibernate team will not address issues reported against these dialect, but the dialect's authors have their own issue tracker.
+
+[NOTE]
+====
+Third-party dialects may not be compatible with all versions of Hibernate ORM.
+
+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.
+====
+
+Below is a list of third-party dialects with links to relevant websites.
+
+[cols="a,a", options="header"]
+|===
+|Dialect |Website
+|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]
+|===
+
 [[community-dialects]]
 == Community dialects
 

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

@@ -72,6 +72,8 @@ driver for your database.
 | Oracle                    | `com.oracle.database.jdbc:ojdbc17:{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 database.
@@ -122,6 +124,13 @@ or `org.eclipse:yasson`
 | <<jfr,Hibernate JFR>>, for monitoring via Java Flight Recorder | `org.hibernate.orm:hibernate-jfr`
 | Hibernate Jandex integration, for <<entity-discovery,entity discovery>> | `org.hibernate.orm:hibernate-scan-jandex`
 | link:{doc-dialect-url}#community-dialects[Community dialects] | `org.hibernate.orm:hibernate-community-dialects`
+| link:{doc-dialect-url}#third-party-dialects[Third-party dialects]
+|
+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
@@ -345,7 +354,7 @@ The properties you really do need to get started are these three:
 ====
 Since 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.
+The only reason to specify this property is if you're using a custom user-written or link:{doc-dialect-url}#third-party-dialects[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

@@ -64,6 +64,25 @@ 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, and in particular link:{doc-dialect-url}#third-party-dialects[third-party dialects], 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.
+
+====
+|`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

@@ -206,6 +206,6 @@ Hibernate abstracts over variations between dialects of SQL via the class `org.h
 - Additional community-supported ``Dialect``s are available in the separate module `hibernate-community-dialects`.
 
 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.)
+An exception is the case of custom or link:{doc-dialect-url}#third-party-dialects[third-party] ``Dialect``s.
 
 NOTE: For information about available dialects and compatible database versions, see the link:{doc-dialect-url}[dialect guide].

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

@@ -16,7 +16,9 @@ The first line of portability for Hibernate is the dialect, which is a specializ
 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.
 
 Hibernate bundles a wide range of dialects for many of the most popular databases: see the link:{doc-dialect-url}[dialect guide] for details.
-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,
+you can check link:{doc-dialect-url}#third-party-dialects[dialects implemented by third parties],
+and as a last resort it is not terribly difficult to write your own.
 
 [[portability-dialectresolver]]
 === Dialect resolution