DataNucleus Problem Reporting

While we always aim to release DataNucleus with as few bugs as possible, it is possible that during the release cycle some issues will come up. Our release process uses more than 1500 unit tests aimed at reproducing the majority of situations that users may come across, though clearly we can never cover all situations with these tests. We also run the JDO3/JPA1 TCKs before each release to provide extra checks to reduce the chance of regressions. The process for reporting issues is defined below :-

  1. Check your input classes, MetaData and persistence code against the JDO/JPA/Jakarta specs and the DataNucleus documentation. The majority of situations are errors in input relative to what DataNucleus allows. Read the LOG. It tells you what is happening. Unwillingness to read basic log information suggests that you don’t want to debug your problem so ask yourself this question why should we if you can’t be bothered?

  2. Search Groups.IO, or Gitter for a similar situation to see if someone else has had the same issue and maybe resolved it.

  3. Try the latest code from GitHub. Things are usually fixed soon after being reported so the issue may no longer be an issue.

  4. Search the issues for the DataNucleus plugin in question for an issue describing your situation. If there is one then you can always check the status of the issue and add a comment against it.

  5. Start a thread on Groups.IO or Gitter. If doing this then seriously consider posting a simple concise testcase (see below) that gives people something that reproduces your problem.

  6. If there is nothing obvious incorrect in your situation and it happens in a released version of DataNucleus then you can raise an issue against the DataNucleus plugin in question. You MUST then create a minimized testcase and attach it to the issue (using "Attach File" on the issue) - see below for testcase definitions. Any problem reports raised without a testcase will be closed. Please don’t take the attitude that this testcase requirement somehow doesn’t apply to you. It is there to demonstrate a problem, so others can see it. Obviously any such problem is not present in all of our tests so yours is different, we aren’t psychic so it is MANDATORY to provide a testcase. ANY "BUG" WITHOUT A TESTCASE WILL BE CLOSED.

Bugs can only be raised against RELEASED versions of DataNucleus and must have a valid testcase attached that demonstrates the issue.

If you encounter a bug that only appears in GitHub latest then you should either report it against an issue related to that item in the current work in progress release, or otherwise report it to developers. This is since something can hardly be a bug if it hasn’t been released yet.

This guide can also be used for providing testcases that demonstrate the need for new features.

A test case is needed to be able to reproduce possible issues. We require something that we can simply take and run ourselves (using Maven). For this reason we have defined a standard for simplified testcases, for JDO, for JPA and for Jakarta as well as building on our existing testcases in GitHub. Please write your testcases using these templates and Maven. If a "test" is to demonstrate something in the Enhancer or SchemaTool then you don’t need the "Test" file since running the Enhancer/SchemaTool via the Maven plugin will show whatever it is.

We sadly do not support other build systems for testcases. You may be more familiar with something else but we are the only people providing our time here, so Maven is the only way, and the Maven build file is pre-configured in these templates below.

JDO Testcase

GitHub You can provide a GitHub JUnit test, cloned from a simple DataNucleus GitHub test project template. DataNucleus provides a template JUnit GitHub project in repository test-jdo. Please fork this and mention the location of your fork on the issue that it relates to. Note that there are two JUnit tests in the provided project, one for single-threaded and one for multi-threaded issues; use the one appropriate to your case and delete the other.

JPA Testcase

GitHub You can provide a GitHub JUnit test, cloned from a simple DataNucleus GitHub test project template. DataNucleus provides a template JUnit GitHub project in repository test-jpa. Please fork this and mention the location of your fork on the issue that it relates to. Note that there are two JUnit tests in the provided project, one for single-threaded and one for multi-threaded issues; use the one appropriate to your case and delete the other.

Jakarta Persistence Testcase

GitHub You can provide a GitHub JUnit test, cloned from a simple DataNucleus GitHub test project template. DataNucleus provides a template JUnit GitHub project in repository test-jakarta. Please fork this and mention the location of your fork on the issue that it relates to. Note that there are two JUnit tests in the provided project, one for single-threaded and one for multi-threaded issues; use the one appropriate to your case and delete the other.

Contributed test for the DataNucleus test suite

As an alternative to the above, and where you are familiar with JUnit and are willing to look at the existing DataNucleus tests in GitHub then please create a JUnit test case that utilises our existing suite of sample data etc. If you provide a testcase in this way your testcase should be a patch against current GitHub latest of the respective test suite project and it should be attached to the issue to which it relates. To add a JUnit testcase, please follow the new unit test guide