Guidelines for XmlBlaster core developers


Getting started

Subscribe to the mailing list and discuss your ideas. And - very important - start hacking.

If you don't like the guidelines, discuss it on the mailing list, enhance them or change them if it makes sense and respects the other core developer feelings.

Coding/documentation should be in English.

Style Guide

Follow the common look and feel of xmlBlaster.
We don't use any tabs for indenting, indenting is done with 3 blanks per level. We know, this discussion is as old as mankind. But we choose for xmlBlaster this way.

Testing - for every feature, a test case.

We have a test suite for xmlBlaster, you find it under xmlBlaster/testsuite/src/java/org/xmlBlaster/test.
Please add a test case there for everything you code.

Because many people develop xmlBlaster, and you develop for the world, we need a full automatic test suite.

Like this, before committing changes, run the tests, and if the test suite shows 'green' we can sleep well.

Believe it or not, this is a MUCH more relaxed developing style. Imagine you make changes or enhancements in somebody else code. You dare much easier to do so, if you know the test suite reports if you broke some parts of the code you didn't understand or wasn't aware of.

Please minimize manual tests on the screen, nobody will run them. There is hopefully always a possibility to test your feature automatically with the test suite.

Steps for testing

You need to start Postgres or Oracle for persistent storage to run the tests, otherwise most tests will fail, see Postgres or Oracle. 

   cd xmlBlaster
   build delete
   build all        (compile the server and the Java clients)
   build c          (compile the C client library for testing)

   build runTests

To get a HTML based test report please invoke after runTests: 

   build report

   Open in your browser:

   xmlBlaster/doc/test/report/html/index.html

NOTE: During development you often want to run only some specific tests manually. Here is an example to run the topic specific tests manually (after compiling everything with build all): 

   cd xmlBlaster/testsuite/src/java/org/xmlBlaster/test/topic
   export CLASSPATH=../../../../../../lib/xmlBlaster.jar:../../../../../../lib/junit.jar
   java junit.swingui.TestRunner -noloading org.xmlBlaster.test.topic.AllTests

Adding a single new test

Every test needs to be added to the AllTests.java file to be automatically invoked. See for example xmlBlaster/testsuite/src/java/org/xmlBlaster/test/topic/AllTests.java

Adding new test subdirectories

If you add a new subdirectory to xmlBlaster/testsuite/src/java/org/xmlBlaster/test for a group of new tests you should add it to the runJunit task in xmlBlaster/build.xml, e.g.: 

   <test name="org.xmlBlaster.test.MYNEWTESTS.AllTests" fork="yes" todir="${report.dir}"/>

Testing client libraries other than Java

To have the tests of client libraries for C, C++, Python etc. integrated into the HTML report you need to add a little wrapper around your native coded tests. You can use the C client library wrapper as an example, see xmlBlaster/testsuite/src/java/org/xmlBlaster/test/C/TestC.java

CHANGES

Please add a short note about your change to the xmlBlaster/CHANGES file.

Requirements

Here you see how the requirements are presented online.

In the directory xmlBlaster/doc/requirements there is one xml file for every xmlBlaster requirement.

Please take a copy of one of those, and note your feature in there. It takes you one minute but allows us to track exactly the state of xmlBlaster.

With XSL style sheets we will generate

  • A html table of supported features in xmlBlaster
  • A list of open topics, where developers can pick some and code it
  • A printable reference manual from xmlBlaster
  • And maybe some other nice with XSL generated output

We are lazy, and this approach is simple and can be done with any vi editor.

The requirement should have a pointer to the testsuite, where this requirement is enforced.

To compile the requirements from XML to nicer HTML use our ant task: 

   cd xmlBlaster
   build requirements

Now for every .xml requirement file a .html counterpart is generated in directory xmlBlaster/doc/requirements. You should only commit the .xml file to subversion as the html files are generated automatically on our homepage server at midnight.

HOME