Hibernate Search

Guide for maintainers

This page contains documentation for current and future maintainers of Hibernate Search.

Releasing

Prepare the release

  • Check that everything has been pushed to the upstream repository.

  • Check that the CI job for the branch you want to release is green.

  • Check there are no outstanding issues in JIRA.

  • If you added a new Maven module that should be included in the distribution, check that it has been included in the distribution (javadoc and ZIP distribution).

    • mvn clean install -Pdocumentation-pdf,dist

    • Check the distribution package as built by Maven (distribution/target/hibernate-search-<version>-dist). In particular, check the jar files in the subdirectories:

      • lib/required

      • lib/optional

      • lib/provided

      They should contain the appropriate dependencies, without duplicates. The creation of these directories is driven by the assembly plugin (distribution/src/main/assembly/dist.xml) which is very specific and might break with the inclusion of new dependencies.

Perform the release

Once you trigger the CI job, it automatically pushes artifacts to the Nexus repository, the distribution to SourceForge and the documentation to docs.jboss.org.

  • Transfer the released issues in JIRA to the "Closed state".

    • Go to this search

    • Select another "fixVersion".

    • Click the button with three dots on the top right corner of the screen and click "Bulk update all XX issues".

    • Use the "Transition" action to transition your issues from "Resolved" to "Closed", and please uncheck the option near the bottom "Send email notifications".

  • Release the version on JIRA.

  • Do not update the changelog.txt and README.md, the release job does it for you.

  • Trigger the release on the CI

    • Go to CI, to the "hibernate-search" 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.

  • Release the artifacts on the JBoss Nexus repository manager.

    • Log into Nexus and examine your staging repository. Use the search box to hide all unrelated repositories: searching for "hibernate" will show only the ones created by hibernate-ci.

    • Test the release in the staging repository.

      You can find more information in the description of the JBoss project release process. A Maven settings.xml for testing the artifacts in the staging repository can be found here.

    • If there is a problem, drop the staging repo, fix the problem, delete the commits pushed by CI and the tag (Note: they have been pushed upstream by CI).

    • If everything is ok, promote the staging repo to the releases repository.

      • For Search 5.x and below, you will also need to "Close" the repository before you can release it.

      • Click "Refresh" after each action.

Announce

  • Update hibernate.org:

    • If it is a new major or minor release, add a _data/projects/search/releases/series.yml file and a search/releases/<version>/index.adoc file.

    • Add a new YAML release file to _data/projects/search/releases.

    • Depending on which series you want to have displayed, make sure to adjust the displayed flag of the series.yml file of the old series.

    • If it’s a .CR or .Final release:

      • Update the Migration Guide; in particular, check the git history for API/SPI changes and document them in the migration guide.

    • If it’s a Final release:

      • Don’t forget to add a line containing stable: true to the new YAML release file.

    • Push to the production branch.

  • Blog about release on in.relation.to. Make sure to use the tags "Hibernate Search" and "Releases" for the blog entry.

  • Send an email to hibernate-announce and CC hibernate-dev.

  • Tweet about the release via @Hibernate. Try to engage with the Lucene community or other communities depending on the release highlights.

  • Update our forum’s sticky post.

Update depending projects

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

  • Upgrade the Hibernate Search dependency in the test case templates.

  • Upgrade the Hibernate Search dependency in the demos.

  • If not already done, create a maintenance branch for the previous series:

Additionally, you should make sure to keep the previous.stable property in the POM up-to-date on all actively developped branches. The property must point to the latest micro of the previous minor. E.g. let’s say you release 5.6.5 while being actively working on 5.7. Then the development branch for 5.7 must have its previous.stable property set to 5.6.5.

Back to top