Guide for maintainers of Hibernate ORM

This guide is intended for maintainers of Hibernate ORM, i.e. anybody with direct push access to the git repository.

Contributing

See CONTRIBUTING.md.

<a id="ci"></a> Continuous integration

Continuous integration is split across two platforms:

• GitHub Actions at https://github.com/hibernate/hibernate-orm/actions
• a self-hosted Jenkins instance at https://ci.hibernate.org.

GitHub Actions workflows

TODO: describe the workflows available.

Jenkins main pipeline

https://ci.hibernate.org/job/hibernate-orm-pipeline/

This job takes care of testing additional DBs for:

• Primary branch builds
• Pull request builds

It is generally triggered on push, but can also be triggered manually, which is particularly useful to test more environments on a pull request.

See Jenkinsfile for the job definition.

Release pipeline

https://ci.hibernate.org/job/hibernate-orm-release/

This job takes care of releases. It is triggered manually.

See ci/release/Jenkinsfile for the job definition.

See Releasing for more information.

<a id="releasing"></a> Releasing

Where is the information

If you're looking for information about how releases are implemented technically, see release/README.adoc.

If you're looking for information about how to release Hibernate ORM, read on.

Automated releases

On select maintenance branches (6.2, 6.4, 7.0, ...), micro releases (x.y.1, x.y.2, ...) are performed on weekends if, since the last release, commits were pushed with a message starting with [HHH- or HHH- -- which is taken as "someone fixed something worthy of a Jira issue".

Make sure to assign fix versions properly in Jira when merging pull requests.

No announcements are expected for such releases: neither through X, blog posts, or email.

Manual releases

On main and some maintenance branches (6.5, ...), automated releases are disabled.

You must perform releases by manually triggering a CI job.

Preparing the release

In any case, before the release:

• Check that everything has been pushed to the upstream repository.
• Check that the CI jobs for the branch you want to release are green.
• Check Jira Releases:
  • Check that the release you are about to publish exists in Jira.
  • Remove the fix version for anything rejected, etc.
  • Move unresolved issues to another version
  • Check there are no resolved/closed issues in the corresponding "work-in-progress version" (e.g. 6.6, 6.6-next, ... naming convention may vary); if there are, you might want to assign them to your release.
• Pull all upstream changes and perform ./gradlew releasePrepare locally.

If it's the first Alpha/Beta of a new major or minor release, before the release:

• Reset the migration guide to include only information relevant to the new major or minor.

If it's a .CR or .Final release, before the release:

• Check that the migration guide is up to date. In particular, check the git history for API/SPI changes and document them in the migration guide.

Performing the release

Trigger the CI release job to automatically publish artifacts and documentation...

• Do not mark the Jira Release as "released" or close issues, the release job triggers Jira automation that does it for you.
• Do not update the repository (in particular changelog.txt and README.md), the release job does it for you.
• Trigger the release on CI:
  • Go to CI, to the "hibernate-orm-release" CI job.
  • Click the "run" button (the green triangle on top of a clock, to the right) next to the branch you want to release.
  • Be careful when filling the form with the build parameters. Note only RELEASE_VERSION is absolutely necessary.
  • Note that for new branches where the job has never run, the first run may not ask for parameters and thus may fail: that's expected, just run it again.

After the job succeeds:

• Update hibernate.org as necessary:
  • If it is a new major or minor release (new "series"):
    • Add a _data/projects/orm/releases/<series>/series.yml file, a orm/releases/<series>/index.adoc file, and a orm/documentation/<series>/index.adoc file. Generally these files can be copied from previous series.
    • If this new series is to support a new JPA release, also be sure to update orm/releases/index.adoc
    • Adjust the release file in _data/projects/orm/releases that was created automatically by the release job: use a meaningful summary, if relevant, and set announcement_url to the blog post, if any.
    • None of the above is necessary for maintenance (micro) releases.
  • Depending on which series you want to have displayed, make sure to adjust the status/displayed attributes of the series.yml file of the old series.
  • Push to the production branch.
• Check that the artifacts are available on Maven Central: https://central.sonatype.com/artifact/org.hibernate.orm/hibernate-core. They should appear after a few minutes, sometimes a few hours.
• Make sure a GitHub release got created and that everything looks ok.

Announcing the release

If it is an Alpha, Beta, CR or first Final (x.y.0.Final) release, announce it:

• Blog about release on in.relation.to. Make sure to use the tags "Hibernate ORM" and "Releases" for the blog entry.
• Send an email to [email protected] and CC [email protected].
• Tweet about the release via the @Hibernate account.
• Announce it anywhere else you wish (BlueSky, etc).

Updating depending projects

If you just released the latest stable, you will need to update other projects:

• Approve and merge automatic updates that dependabot will send (it might take ~24h):
  • In the test case templates.
  • In the demos.
• If it's a .Final release, upgrade the Hibernate ORM dependency manually:
  • In the Quarkus BOM.
  • In any other relevant project.

Updating Hibernate ORM

In any case:

• Reset release_notes.md.

If it is a new major or minor release:

• Reset the migration guide on the main branch if you forgot about it when preparing the release.
• Create a maintenance branch for the previous series, if necessary; see branching.

Setting up the maintenance branch

Once the release series (e.g. 7.2) is branched out and goes into maintenance mode make sure to:

• Enable automated releases (for that branch)
  • Update Jenkinsfile and switch RELEASE_ON_SCHEDULE to true
• Remove the nightly Jenkins job from that branch (nightly.Jenkinsfile)
• Update GitHub workflows:
  • For ci.yml / codeql.yml
    • remove the branch push triggers (on.pushbranches)
    • update branch in the pull request triggers
• Enable Quarkus testing job (in necessary)
  • In quarkus.Jenkinsfile switch ENABLE_QUARKUS_BUILDS to true and update QUARKUS_BRANCH_TO_TEST as necessary.
• Update main build Jenkinsfile (for the branch)
  • Enable JDK testing in the build by removing the conditions under Don't build environments for newer JDKs
  • Stop running this build for pushes to the branch
• Update TCK job jpa-3.2-tck.Jenkinsfile to always run for PRs and not for the pushes to the branch