Developers Guide

Here you find all information needed to contribute good code. These are naming conventions, heading comments, javadoc and unit tests.

Java File Headers

For new class files this header is recommended.

    /*
     *
     * The DbUnit Database Testing Framework
     * Copyright (C)2002-2020, dbunit.sourceforge.net
     *
     * This library is free software; you can redistribute it and/or
     * modify it under the terms of the GNU Lesser General Public
     * License as published by the Free Software Foundation; either
     * version 2.1 of the License, or (at your option) any later version.
     *
     * This library is distributed in the hope that it will be useful,
     * but WITHOUT ANY WARRANTY; without even the implied warranty of
     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     * Lesser General Public License for more details.
     *
     * You should have received a copy of the GNU Lesser General Public
     * License along with this library; if not, write to the Free Software
     * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
     *
     */

For java class definitions this header is recommended.

    /**
     * @author <developer> (<sf-user-name> AT users.sourceforge.net)
     * @since <dbunit-version>
     */

Here an example:

    /**
     * @author gommma (gommma AT users.sourceforge.net)
     * @since 2.4.0
     */

Besides the standard javadoc tags it is desired to also add the dbunit version in which the method was introduced. This lets users and developers keep track of the changes that are made to the old/existing API.

    /**
     * @param myValue <some comment>
     * @since <dbunit-version>
     */
    public void assertSomething(String myValue) {
    ...

Track Changes with Tickets

If one does not already exist, create a bug or feature ticket for the change.

Merge Requests or Patches

The easier you make it for dbUnit committers to apply changes, the more likely they will apply the changes.

Contribute changes using merge requests from your fork (preferred) or patches attached to tickets.

Tests are Critical

Include tests proving the change fixes the issue or the new feature works. They especially help with understanding and long term quality, proving future changes do not break the feature.

Update Docs

Update relevant and/or create doc pages for the change and include them in the commit with the code changes.

Update changes.xml

changes.xml is how users easily see a release's change highlights.

  • Add an entry for the change to changes.xml in the forthcoming release's section. Place new entries after the existing ones.
  • Include a terse summary at the end of description attribute.
  • See existing entries for examples.

Include this file in the commit with the code changes.

Format Code

  • Follow the existing files' conventions as best possible.
  • If using Eclipse, please import the formatter preference file java-codestyle-formatter.xml located in repository root directory.
  • When a file has more than a small formatting correction with your changes, commit the formatting corrections in a separate commit with message "Reformat only". Mixing formatting corrections with logic changes creates difficult code reviews and historical change reviews.

Commit Messages

Keep Current with Master

Rebase on master to keep your branch updated. Always check if needing a rebase just before creating the merge request or asking for review.

Run the DbUnit Tests

Verify the build is clean with your changes and tests by running the dbUnit unit and integration tests against all the supported databases. Refer to Integration Tests for setup and running them.

Discussions and Questions

For questions, assistance, or other help, please comment on the tracker item, merge request, or email the dev list.