Installing Plugins

Some of the Hibernate projects use Maven, some others use Gradle. After you check out the project from GitHub check if there is a pom.xml file in the root of the sources: that means it's a Maven project. If there is a build.gradle file instead, then you will need to use Gradle to build it.

Contributing to a Maven based project in Eclipse

We recommend to use the excellent m2e plugin.  This plugin is commonly already installed in Eclipse; if you suspect it's missing you should be able to find it under Help -> Install New Software.

When importing an Hibernate project using m2e this might suggest to install additional plugins, for example to handle annotation processors. It will ask for permission to automatically download the additional plugins; we suggest to allow this as it simplifies development.

Contributing to a Gradle based project in Eclipse

You will need to install "Buildship", the Gradle tools for Eclipse.

Installing it is very simple; the following guide provides a step by step tutorial:

Using the Gradle build system in the Eclipse IDE - Tutorial

After having installed the Gradle tooling, import the project using the "gradle wrapper" approach - which is the default. This might take several minutes, as the Gradle build might need to download dependencies in the background, or do some work to analyze the project.

Specific instructions for Hibernate ORM in Eclipse

If you're importing the flagship project Hibernate ORM, the import process gets a bit more tedious as the Eclipse/Gradle integration is still a bit limited.

After importing the project, you will have Eclipse mention several errors because of "circular dependency problems". The project actually doesn't have any circular dependency but the Gradle integration leads it to believe this; you will have to go in Window -> Preferences -> Java -> Compiler -> Building, find the "Circular Dependencies" problem and have it ignore the problem by changing it to "Warning" rather than "Error".

Next, for several modules you will have to manually add some generated sources to the source folders. For example for the hibernate-core module, you will need to add target/generated-src/antlr/main, target/generated-src/apt/main, target/generated-src/apt/test and target/generated-src/jaxb/main. Note that these directories might be hidden by default, check your Filter options and uncheck "Gradle build folder". Use "Build Path" -> "Use as Source Folder" on each of these.

Finally, you will have to manually add the ANT and JBoss Logger dependencies.

Code formatting

From the Eclipse menu Window, Preferences, select Java - Code Style - Formatter. Import the hibernate-java-formatting.xml from GitHub to apply the style the Hibernate team uses consistently across the codebase.

Please avoid re-formatting large parts of code, especially when providing a patch we would love to have the diffs highlight the changes which matter.

If you feel the need to fix formatting on an existing source file, make sure your commit contains exclusively formatting changes (avoid any functional change) and make sure the commit comment mentions this.

Code templates

In the same Preferences menu, select Java - Code Style - Code Templates and import the appropriate file from our GitHub repository:

• For Hibernate ORM: hibernate-code-templates-orm.xml
• For Hibernate Search: hibernate-code-templates-search.xml
• For Hibernate OGM: hibernate-code-templates-ogm.xml
• For Hibernate Validator: hibernate-code-templates-validator.xml

This will automatically import proper license headers into new files. Feel free to add your nick or full name as author of new files, and optionally provide an email. The copyright header is a requirement.

You can also use the hibernate-auto-cleanup.xml to be imported into Java -> Code Style -> Clean Up.

Unit test

Hibernate is developed applying test-driven development. If you plan to contribute any new code, providing a test is important for many reasons, not least to help maintainers understand your code. Including appropriate tests with your patches / pull request will greatly speed-up inclusion of it.

We have continuous integration tests covering many many different databases; you're expected to have verified your tests where you can and at least on H2 (the default in memory database included in the testsuite) but you don't have to try it out on all possibly supported databases, we'll let the continuous integration know, and get back to you and help as we can if some compatibility problem is highlighted.

Make sure your tests close all resources - even in case of failures - and cleanup after themselves (e.g. delete temporary directories if you needed any).

See also Writing tests.

Running tests in Eclipse

Some tests involving integration with JGroups and/or Infinispan will start a network connection to themselves (via localhost) to simulate a cluster of computers. Many JVMs default to IPv6 for this, so either you have that configured correctly or you might want to start tests with these JVM properties set:

-Djava.net.preferIPv4Stack=true -Djgroups.bind_addr=127.0.0.1

Debugging

When debugging, Eclipse might invoke toString() methods on the objects you select for inspection. This operation could trigger initialization of proxies and so affect the debugged object state. Using Eclipse you can customize the way it shows objects: look into "Detail formatters" and the Idea wiki page for some ideas. You could avoid including lazy-loaded details in your toString() implementations: it also helps to avoid unintended loading during logging, a frequent mistake having terrible effects on performance.