HHH-18861 - Improve GitHub release announcement body for automated releases

[sebersole]

HHH-18861 - Improve GitHub release announcement body for automated releases

https://hibernate.atlassian.net/browse/HHH-18861

Requires hibernate/hibernate-release-scripts#23

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license
and can be relicensed under the terms of the LGPL v2.1 license in the future at the maintainers' discretion.
For more information on licensing, please check here.

---

[beikov]

Since GitHub uses Markdown, using the release_announcement.adoc directly won't work unfortunately. See for yourself how this file would look like when being interpreted by the GitHub Markdown rendering engine:

👪 7.0

:docs-url: https://docs.jboss.org/hibernate/orm/{family}
:javadocs-url: {docs-url}/javadocs
:migration-guide-url: {docs-url}/migration-guide/migration-guide.html
:intro-guide-url: {docs-url}/introduction/html_single/Hibernate_Introduction.html
:user-guide-url: {docs-url}/userguide/html_single/Hibernate_User_Guide.html
:ql-guide-url: {docs-url}/querylanguage/html_single/Hibernate_Query_Language.html

[[jpa-32]]
== Jakarta Persistence 3.2

7.0 migrates to Jakarta Persistence 3.2 which can be fairly disruptive. See the link:{migration-guide-url}#jpa-32[Migration Guide] for details.

See https://in.relation.to/2024/04/01/jakarta-persistence-3/[this blog post] for a summary of the changes in 3.2

• https://ci.hibernate.org/view/ORM/job/hibernate-orm-tck-3.2/job/wip%252F7.0/24/[TCK Results] with Java 17
• https://ci.hibernate.org/view/ORM/job/hibernate-orm-tck-3.2/job/wip%252F7.0/25/[TCK Results] with Java 21

[[java-17]]
== Java 17

Version 3.2 of Jakarta Persistence requires Java 17. Hibernate 7.0 therefore baselines on Java 17 whereas previous versions baseline on Java 11.

[[model-validations]]
== Domain Model Validations

7.0 does much more validation of an application's domain model and especially its mapping details, e.g.

• illegal combinations such as @Basic and @ManyToOne on the same attribute
• misplaced annotations such as an annotated getter method with FIELD access
• stricter following of JavaBean conventions

See the link:{migration-guide-url}#annotation-validation[Migration Guide] for details.

[[mapping-xml]]
== mapping.xsd

Hibernate 7.0 provides a new XSD that represents an "extension" of the Jakarta Persistence orm.xsd weaving in Hibernate-specific mapping features. The namespace for this extended mapping is http://www.hibernate.org/xsd/orm/mapping

For applications using Hibernate's legacy hbm.xml format, we provide a tool to help with the transformation.
See the link:{migration-guide-url}#hbm-transform[Migration Guide] for details.

[[hibernate-models]]
== Hibernate Models

7.0 migrates from https://github.com/hibernate/hibernate-commons-annotations/[Hibernate Commons Annotations] (HCANN) to the new https://github.com/hibernate/hibernate-models[Hibernate Models] project for low-level processing of an application domain model, reading annotations and weaving in XML mapping documents.

See the link:{migration-guide-url}#hibernate-models[Migration Guide] for details.

[[json-and-xml-functions]]
== JSON and XML functions

Support for most of the JSON and XML functions that the SQL standard specifies was added to HQL/Criteria.
The implementations retain the SQL standard semantics and will throw an error if emulation on a database is impossible.

New functions include:

• construction functions like json_array(), json_object(), xmlelement() and xmlforest()
• query functions like json_value(), json_query() and xmlquery()
• aggregation functions like json_agg(), json_object_agg() and xmlagg()
• manipulation functions like json_set(), json_mergepatch()
• any many more

NOTE: The functions are incubating/tech-preview and to use them in HQL,
it is necessary to enable the hibernate.query.hql.json_functions_enabled and hibernate.query.hql.xml_functions_enabled configuration settings.

[[set-returning-functions]]
== Set-returning Functions

A set-returning function is a new type of function that can return rows and is exclusive to the from clause.
The concept is known in many different database SQL dialects and is sometimes referred to as table valued function or table function.

Custom set-returning functions can be registered via a FunctionContributor.
Out-of-the-box, some common set-returning functions are already supported or emulated

• unnest() - allows to turn an array into rows
• generate_series() - can be used to create a series of values as rows
• json_table() - turns a JSON document into rows
• xmltable() - turns an XML document into rows

[[any-discriminator]]
== @AnyDiscriminatorImplicitValues

The new @AnyDiscriminatorImplicitValues offers 2 related improvements for the mapping of discriminator values
for @Any and ManyToAny associations.

First, it allows control over how Hibernate determines the discriminator value to store in the database for
implicit discriminator mappings. Historically, Hibernate would always use the full name of the associated
entity.

Second, it allows mixing of explicit and implicit value strategies.

See the link:{user-guide-url}#associations-any[User Guide] for details.

[[cleanup]]
== Clean-up

A lot of deprecated contracts and behavior has been removed. See the link:{migration-guide-url}#cleanup[Migration Guide] for details.

[beikov]

So either we write the release announcement in markdown, or we do some sort of rendering/conversion before passing the content to the script.

[sebersole]

Good point.

Writing that fragment in markdown is probably the easiest solution, though a tad unfortunate.

[sebersole]

Squashed and applied manually