0.1. Reporting Bugs

Introduction

So you found a bug in ApacheDS. Don't worry this is a good thing! We can fix it really fast but need your help. There are different degrees to your ability to help out. Some of you have developer skills so you might be able to write a test case that pin points that bug. If you can do this we will prioritize your bug report above all others. Yes we will put your bug to the top most important fixes that should be fixed first. But if you can't do this and your bug is serious then we're prioritize it ahead of others anyway.

This wiki page shows you how you can help us to help you!!!

Creating a testcase project: using the apacheds-testcase-archetype.

We've created a simple archetype for you to rapidly create a Maven project that fires up ApacheDS in embedded mode within a JUnit testcase. This test case will start up ApacheDS as a server on any available port above 1024 on your machine. It will then initialize a JNDI context to the ou=system partition using the SUN JNDI LDAP provider going over the wire on that port above 1024.

So you can write client code in your test case immediately to use this ctx member of the unit test. Just add your code, tar gzip the project, and attach it to your JIRA issue on the ApacheDS JIRA here:

https://issues.apache.org/jira/browse/DIRSERVER

We'll prioritize your bug higher than others and probably fix it rapidly because the problem is isolated thanks to your testcase submission. We will in fact strip out your testcase and add it to our suite of test cases to make sure ApacheDS always passes this integration test you've provided.

Installing the apacheds-testcase-archetype

To use the archetype you'll need to check it out and install it. Here's how you can do that for the leading edge of the 1.0 branch:

svn co http://svn.apache.org/repos/asf/directory/branches/apacheds/1.0/testcase-archetype
cd testcase-archetype
mvn install

This will install the archetype onto your local repository. Now you can invoke the archetype.

Invoking (running) the archetype: generating the testcase project

Once you checkout the archetype plugin and install it you can use it like so to generate a foo-test project:

mvn archetype:create -DarchetypeGroupId=org.apache.directory.server \
                     -DarchetypeArtifactId=apacheds-testcase-archetype \
                     -DarchetypeVersion=1.0-RC4-SNAPSHOT \
                     -DgroupId=com.acme -DartifactId=foo-test

This will generate the default test case project with the following tree structure:

akarasulu@newton:~/foo-test$ tree
.
|-- pom.xml
`-- src
    |-- main
    |   |-- java
    |   |   `-- com
    |   |       `-- acme
    |   |           `-- Dummy.java
    |   `-- resources
    `-- test
        |-- java
        |   `-- com
        |       `-- acme
        |           `-- ApacheDSITest.java
        `-- resources
            `-- log4j.properties

11 directories, 4 files

• Dummy.java - this is just a placeholder file to make sure that Maven works properly.
• ApacheDSITest - the ApacheDS Integration Test that contains an testExample method for you to customize
• pom.xml - the Maven Project Object Model (POM) for your new testcase project (can remain as is)
• log4j.properties - Log4j configuration file that controls ApacheDS logging for your convenience; edit this file to control logging output

Once you do this you can cd into foo-test and just build and test it for fun to see what happens. This will build, and test the default test case (does nothing) that comes package with the project you just created. This test case does nothing but it does start ApacheDS in embedded mode within the test case's setUp() method and creates a JNDI context connected to this server instance. CD into foo-test and run the following command:

mvn test

Now you can customize the ApacheDSITest.java file to isolate your bug. Open ApacheDSITest.java with your favorite editor and goto town. However if you want to pull this project into your IDE and edit it there you can use Maven's IDEA, Eclipse and Netbeans integration to create IDE project descriptors for them. Then you can import this project into your IDE. Here's how:

For IDEA

mvn idea:idea

For Eclipse

mvn eclipse:eclipse

For Netbeans

See this page: http://maven.apache.org/guides/mini/guide-ide-netbeans/guide-ide-netbeans.html.

Note about releases and the 1.0 branch

Note that every different release of ApacheDS after RC3 will have a different set of deps for this archetype. So release specific archetypes will exist. Just use that release's archetype to submit testcases for your bugs on the respective version of ApacheDS.

This makes test cases specific to the release of ApacheDS where we can easily isolate your bug found in that release and commit a fix for it fast.

Why a Maven Archetype for Testing?

1. Easy and fast to start integration testing ApacheDS.
2. We (developers of ApacheDS) can use it ourselves.
3. We want users of ApacheDS to help us help them.
4. Users need to customize a project with perhaps additional dependencies.
5. Users can add many test cases to the project.
6. Tests isolating custom bugs can be incorporated into our community test suite for ApacheDS.