Section : Documentation

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 spec and the DataNucleus documentation. The majority of situations are errors in input relative to what DataNucleus allows. More importantly than this, READ THE LOG. IT TELLS YOU WHAT IS HAPPENING. Unwillingness to read such basic log information suggests that you dont want to debug your problem so ask yourself this question why should we if you cant be bothered?
  2. Search the Forum for a similar situation to see if someone else has had the same issue and maybe resolved it.
  3. Try the latest Nightly Builds. Things are usually fixed soon after being reported so the issue may no longer be an issue (if there are no jars present in the nightly repo then nothing has changed since the previous release).
  4. Search JIRA for an issue describing your situation. If there is one then you can always check the status of the issue and post against it in JIRA.
  5. Start a thread on the Forum. 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 in JIRA. You should then create a testcase and attach it to the JIRA issue (using Attach File on the issue) - see below. Bugs can only be raised against RELEASED versions of DataNucleus. If you encounter a bug that only appears in GitHub latest then you should either report it against a JIRA 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 hasnt been released yet. Please dont take the attitude that this testcase requirement somehow doesnt 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 arent psychic so require a testcase.

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. For this reason we have defined a standard for simplified testcases, for JDO, and for JPA as well as building on our existing testcases in GitHub. Please write your testcases using these templates.

JDO Testcase : GitHub JUnit test, cloned from DataNucleus project

GitHub DataNucleus provides a template JUnit GitHub project in repository test-jdo. Please fork this and mention the location of your fork on the JIRA 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 JUnit test, cloned from DataNucleus project

GitHub DataNucleus provides a template JUnit GitHub project in repository test-jpa. Please fork this and mention the location of your fork on the JIRA 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.

JDO/JPA : JUnit test built on 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 JIRA issue to which it relates. To add a JUnit testcase, please follow the new unit test guide