Hibernate OGM

Contribute

Project on GitHub
Issue tracker

Hibernate OGM is not maintained anymore.

Hibernate OGM is a young project. The code, the direction and the documentation are all in flux and being built by the community. Join and help us shape it!

How to get help

First of all, make sure to read this reference documentation. This is the most comprehensive formal source of information. Of course, it is not perfect: feel free to come and ask for help, comment or propose improvements in our Hibernate OGM forum.

You can also:

  • open bug reports in JIRA

  • propose improvements on the development mailing list

  • join us on IRC to discuss developments and improvements (#hibernate-dev on freenode.net; you need to be registered on freenode: the room does not accept "anonymous" users).

How to contribute

Welcome!

There are many ways to contribute:

  • report bugs in JIRA

  • give feedback in the forum, Zulip or the development mailing list

  • improve the documentation

  • fix bugs or contribute new features

  • propose and code a datastore dialect for your favorite NoSQL engine

Hibernate OGM’s code is available on GitHub at https://github.com/hibernate/hibernate-ogm.

How to build Hibernate OGM

Hibernate OGM uses Git and Maven 3, make sure to have both installed on your system.

Clone the git repository from GitHub:

git clone https://github.com/hibernate/hibernate-ogm
cd hibernate-ogm

Run maven

mvn clean install -s settings-example.xml

Note that Hibernate OGM uses artifacts from the Maven repository hosted by JBoss. Make sure to either use the -s settings-example.xml option or adjust your ~/.m2/settings.xml according to the descriptions available on this jboss.org wiki page.

Note that for running the test suite against separately installed MongoDB and CouchDB servers their host name must be specified via an environment variable. See the sections below for the details.

To speed things up, there are several options for skipping parts of the build. To run the minimum project build without integration tests, documentation and distribution execute:

mvn clean install -DskipITs -DskipDocs -DskipDistro -s settings-example.xml

The following sections describe these options in more detail.

Integration tests

Integration tests per default download the WildFly application server, unpack the modules in it and run the tests using Arquillian. You can skip integration tests by specifying the skipITs property:

mvn clean install -DskipITs -s settings-example.xml
MongoDB

For executing the tests in the mongodb and integrationtest/mongodb modules, the embedmongo-maven-plugin is used. It downloads the MongoDB distribution, extracts it, starts a mongod process and shuts it down after test execution.

If required, you can configure the port to which the MongoDB instance binds to (by default 27018) and the target directory for the extracted binary (defaults to ${project.build.directory}/embeddedMongoDb/extracted) like this:

mvn clean install -s settings-example.xml -DembeddedMongoDbTempDir=<my-temp-dir> -DembeddedMongoDbPort=<my-port>

To work with a separately installed MongoDB instance instead, specify the useExternalMongoDb property:

mvn clean install -s settings-example.xml -DuseExternalMongoDb

This assumes MongoDB to be installed on localhost, using the default port and no authentication. If you work with different settings, configure the required properties in hibernate.properties (for the tests in mongodb) and/or the environment variables MONGODB_HOSTNAME MONGODB_PORT MONGODB_USERNAME MONGODB_PASSWORD (for the tests in integrationtest/mongodb) prior to running the tests:

export MONGODB_HOSTNAME=mongodb-machine
export MONGODB_PORT=1234
export MONGODB_USERNAME=someUsername
export MONGODB_PASSWORD=someP@ssw0rd
mvn clean install -s settings-example.xml
CouchDB

For running the tests in the couchdb module an installed CouchDB server is required. Specify its host name by setting the environment variable COUCHDB_HOSTNAME prior to running the test suite:

export COUCHDB_HOSTNAME=couchdb-machine

If this variable is not set, the couchdb module still will be compiled and packaged but the tests will be skipped.

Documentation

The documentation is built by default as part of the project build. You can skip it by specifying the skipDocs property:

mvn clean install -DskipDocs -s settings-example.xml

If you just want to build the documentation, run it from the documentation/manual subdirectory.

For rapid documentation testing, you can limit the generated format to html to speed up the process

mvn clean install -f documentation/manual/pom.xml -s settings-example.xml -Djdocbook.format=html_single

Distribution

The distribution bundle is built by default as part of the project build. You can skip it by specifying the skipDistro property:

mvn clean install -DskipDistro -s settings-example.xml

Make sure to check the readme.md in the source root directory for further build options.

How are the tests structured?

Core tests

There are two types of tests in core:

  1. Unit tests for stuff in core itself

  2. And the "backendtck" which are high-level (i.e. Session/EM-level) tests and which are executed for all backends. This is our backend TCK.

To run a specific test against a specific store in Eclipse, simplest is to use the <StoreName>BackendTckHelper class to run the test.

For instance, if you want to run the BuiltInTypeTest test for Neo4j, open the Neo4JBackendTckHelper class in your IDE and make the @ClasspathSuite.ClassnameFilters annotation look like:

@ClasspathSuite.ClassnameFilters({ ".*BuiltInTypeTest" })

Then simply run Neo4JBackendTckHelper as a JUnit test in your IDE.

Tests specific to a dialect

As for the unit tests specific to a dialect, you can just run the test as a JUnit test in your IDE.

Code organization

Packages are organized with the SPI/impl split at the lowest level. SPI is geared towards grid dialect implementors. The split is not complete yet, as some parts of "our" dialects refer to "impl" classes from core. Anything not "spi" or "impl" is public API.

How to contribute code effectively

The best way to share code is to fork the Hibernate OGM repository on GitHub, create a branch and open a pull request when you are ready. Make sure to rebase your pull request on the latest version of the master branch before offering it.

Here are a couple of approaches the team follows:

  • We do small independent commits for each code change. In particular, we do not mix stylistic code changes (import, typos, etc) and new features in the same commit.

  • Commit messages follow this convention: the JIRA issue number, a short commit summary, an empty line, a longer description if needed. Make sure to limit line length to 80 characters, even at this day and age it makes for more readable commit comments.

OGM-123 Summary of commit operation

Optional details on the commit
and a longer description can be
added here.

  • A pull request can contain several commits but should be self contained: include the implementation, its unit tests, its documentation and javadoc changes if needed.

  • All commits are proposed via pull requests and reviewed by another member of the team before being pushed to the reference repository. That’s right, we never commit directly upstream without code review.

Back to top