Working from the source code

1 Source code repository

We use the SourceForge.net infrastructure for our SVN repository. The repository follows a very common layout with /trunk, /branches and /tags (i.e. versions) under the repository root.

The SVN repository root is: http://svn.code.sf.net/p/jppf-project/code/

2 Versioning policy

• there is normally a version tag for each released version (like v_2_1 for version 2.1, etc.)
• any version that includes new features will be numbered in x.y form for minor versions, and x.0 for major versions. We're not exactly clear on the distinction between minor vs. major, however the rule of thumb is that if a major refactoring was involved, especially to enable new major features, then it is a major version
• a version that only includes bug fixes is numbered in the form x.y.z. We call these technical releases, as they contain no new feature
• if we can provide a patch to our users and they are satisfied with it then that's what we do. It's much simpler and faster than releasing a new version

3 Branching policy

• the fewer branches, the better!
• branches are created when working on major new features in the trunk, and new minor features have been requested by the users. We keep working on the major stuff on the trunk, and create a new branch for the minor modifications and enhancements
• branches are created from tagged versions, based on the latest release. For instance, the latest version was v2.4 (tag v_2_4), if we were to create a new branch now, we would create b_2_4. Then depending on major vs. minor work on the trunk, the next version based on this branch would be v_2_5 (new features that cannot wait the next major version) or v_2_4_1 (bug fixes only).
• we only work on the trunk and the latest branch. Bug fixes are committed to both branches, as are minor new features. Major new features are committed to the trunk only.

4 Patches

We have a section of the web site dedicated to patches. These allow us to release bug fixes quickly in a formal way, and avoid a full release cycle once a bug has been fixed. It's proved quite effective so far.

5 Development and build environment

Development is done with the Eclipse IDE. Here we are not discussing the merits of Eclipse versus other IDEs. This is just what we use. Two additional plugins are required: Subclipse to integrate with SVN, and Checkstyle, to enforce the consistency of the code metrics and documentation.

Initial SVN checkout and creation of the Eclipse workspace and projects can be made in one single step by importing this Eclipse project set file for the trunk, or this project set for branch 3.3 for the latest release (v3.3.x).

A full build of the JPPF distribution can be performed using the Ant build script found at: "JPPF_WORKSPACE/JPPF/bin/build.xml" and running the "deploy" target: "ant deploy". This will build all modules, distribution zip files, and even the web site.

6 Testing

There are 2 modules / projects dedicated to automated testing:

• "tests" provides a framework and a set of automated tests based on JUnit to ensure that JPPF features are working as expected and that no regression were introduced in the latest code. These tests start actual drivers and nodes, and manage the corresponding processes. So they're more than unit tests. They do, however, ensure that a large set of the features are covered. To run the tests, open a command prompt in JPPF_WORKSPACE/tests and type: "ant run". A number of JUnit launch configuration are also provided in test/launches, so the tests can be run from within the IDE, as any other JUnit test.
• "stress-tests" provides a sophisticated framework for testing the resilience and stability of a JPPF grid under load and stress conditions. It makes it really easy to define sophisticated topologies via a very few configuration properties. See its Readme.txt for an overview of what it can do.

7 Code metrics and documentation constraints

Via Checkstyle, we attempt to enforce the following:

• A header, with the copyright disclaimer and license terms, must be present at the start of each file (Java, configuration, XML files, etc.). Using Eclipse code and documentation templates for this is quite handy and painless.
• there must be a Javadoc for each and all Java artifacts, no matter their visibility level: classes, instance and static variables, methods. {@inheritDoc} tags are accepted for overridden methods, when there is no significant implementation details to document.
• Java files can be 600 hundred lines long at most. If it gets longer, split it. It may seem unduly constraining, however it forces the developers to really think about how they write their code, and as far as we know, results in a clearer code and class design. It also leads to more frequent refactorings and provides a better survivability of the design. This has worked great during all the years of JPPF development.
• Methods can be no more than 80 lines long. If a method goes over this limit, split it.

There are few exceptions to these rules, essentially in Java files that we imported directly from other sources with a compatible license or from the public domain. We are still working on that.

You can find actual code metrics on the Ohloh page for JPPF.

8 JPPF Maven artifacts

Starting from JPPF 3.3, we are now publishing the main JPPF artifacts to Maven Central:
http://search.maven.org/#search|ga|1|jppf

You can also find the public snapshots and releases on Sonatype's public repository:
https://oss.sonatype.org/content/groups/public/org/jppf/