The goal is to have a dedicated document for these “release notes”, similar to the migration guide but focused on new features and enhancements. It answers the question “what’s new, what do I get from upgrading?”.

We currently put that in a dedicated section in the website, but we recently added the ability to replace that section with an external link.

To do:

1. Add a file in the documentation alongside the migration guide, with details of new features and enhancements.

2. Make sure that file will be published along with the rest of the documentation upon releases.

3. Adjust whatever creates the “Release” (~tag) on GitHub so that the description of the “Release” simply links to the release notes and migration guide. This involves in particular:

   1. removing release_notes.md and any reference to it in ci/release/Jenkinsfile

   2. finding a way to let the release scripts know where the release notes and migration guide are (for the version family being released)

   3. using that knowledge in release scripts to generate a “Release” description

4. Upon the next release release, update hibernate.org to link to that new documentation file. Something similar to this: