| name | migration-guide |
| description | Generate a Quarkus migration guide entry for a Hibernate version upgrade, in asciidoc format ready for the Quarkus wiki |
Migration Guide Generator
Usage: /migration-guide — run from within a feature directory that has a Hibernate version bump committed.
Generates a Quarkus migration guide entry in asciidoc format, ready to be copied to the Quarkus wiki.
Instructions
-
Clone the Quarkus wiki repo into the feature directory and read earlier migration guide files to match style:
git clone --depth 1 https://github.com/quarkusio/quarkus.wiki.git ~/git/hibernate/<feature>/quarkus-wiki
Read files like Migration-Guide-3.26.asciidoc for style reference. This is much faster than web searches.
-
Read the commits that bump the Hibernate versions to identify the old and new versions of:
- Hibernate ORM
- Hibernate Reactive
- Hibernate Search
-
For Hibernate ORM, fetch the migration guide from https://docs.hibernate.org/orm/<NEW_VERSION>/migration-guide/ and extract:
- API changes (removed/deprecated annotations, classes, methods)
- SPI changes (if relevant to applications)
- Behavioral changes (changed semantics, stricter validation, spec compliance)
- DDL changes (schema generation differences)
- Keep it concise — synthesize, don't copy verbatim. Link back to upstream guide sections.
- Use the exact HTML anchors from the upstream guide (inspect the page). Anchors for named sections use the format
#section-id, while auto-generated ones use #_underscored_title.
-
For minimum database versions, compare the dialect pages between old and new ORM versions:
- Old:
https://docs.hibernate.org/orm/<OLD_VERSION>/dialect/dialect.html
- New:
https://docs.hibernate.org/orm/<NEW_VERSION>/dialect/dialect.html
- Only list databases where the minimum version actually changed.
-
For Hibernate Reactive, write a short section noting it was upgraded and that breaking changes are inherited from Hibernate ORM (listed above). If Reactive was not upgraded, note that.
-
For Hibernate Search, fetch the migration guide from https://docs.hibernate.org/search/<NEW_VERSION>/migration/html_single/ and summarize. If fully backwards-compatible, say so briefly.
-
Check for Elasticsearch/OpenSearch Dev Services version bumps by looking at recent commits on the branch for changes to elasticsearch-server.version, opensearch-server.version, and elasticsearch-opensource-components.version in build-parent/pom.xml and bom/application/pom.xml. If any changed, add a section noting the old and new default versions.
-
Write the output to migration-guide.asciidoc in the feature's quarkus worktree root.
Output Format
Follow the style of the raw asciidoc in the wiki repo. The heading structure uses == for top-level component groupings and === for subsections:
== Hibernate ORM
=== Upgrade to Hibernate ORM <version>
The Quarkus extension for Hibernate ORM was upgraded to Hibernate ORM <version>.
Hibernate ORM <version> includes several behavioral changes. Below are the ones most likely to affect existing applications.
Refer to the https://docs.hibernate.org/orm/<version>/migration-guide/[Hibernate ORM <version> migration guide] for more information.
=== API changes
* https://docs.hibernate.org/orm/<version>/migration-guide/#anchor[Description of change].
=== Behavioral changes
* https://docs.hibernate.org/orm/<version>/migration-guide/#anchor[Description of change].
=== DDL changes
* https://docs.hibernate.org/orm/<version>/migration-guide/#anchor[Description of change].
=== Minimum database versions
* DatabaseName: bumped minimum version from X to Y
See https://docs.hibernate.org/orm/<version>/dialect/dialect.html[here] for details on the current minimum versions.
== Hibernate Reactive
=== Upgrade to Hibernate Reactive <version>
The Quarkus extension for Hibernate Reactive was upgraded to Hibernate Reactive <version>.
Hibernate Reactive <version> is backwards-compatible with Hibernate Reactive <previous>, with the exception of a few breaking changes inherited from Hibernate ORM and listed above.
== Hibernate Search
=== Upgrade to Hibernate Search <version>
The Quarkus extensions for Hibernate Search were upgraded to Hibernate Search <version>.
<Compatibility summary>.
Refer to the https://docs.hibernate.org/search/<version>/migration/html_single/[Hibernate Search <version> migration guide] for more information.
== Elasticsearch and OpenSearch Dev Services
The Elasticsearch Dev Services now default to starting Elasticsearch <new>, instead of <old> previously.
The OpenSearch Dev Services now default to starting OpenSearch <new>, instead of <old> previously.
The Elasticsearch Java client was also upgraded from <old> to <new>.
Key Rules
- Only cover breaking changes and behavioral differences. Do not include new features — those belong in release notes, not the migration guide.
- This is a synthesis, not a copy of the upstream guide. Be concise.
- Use asciidoc link syntax:
https://url[link text]
- Every bullet point should link to the relevant upstream migration guide section with the correct anchor.
- Omit subsections that have no changes (e.g., skip "DDL changes" if there are none).
- If minimum database versions haven't changed, either omit the section or note "No changes compared to previous version."
