JBoss.orgCommunity Documentation

Chapter 2. Developer tools

2.1. Development methodology
2.2. JDK
2.3. JIRA
2.4. Subversion
2.5. Git
2.6. Maven
2.6.1. Building
2.7. Continuous integration with Hudson
2.8. Eclipse IDE
2.9. Releasing
2.9.1. Building all artifacts and assemblies
2.9.2. Determine the version to be released
2.9.3. Release dry run
2.9.4. Prepare for the release
2.9.5. Perform the release
2.10. Summary

The ModeShape project uses Maven as its primary build tool, Subversion for its source code repository, JIRA for the issue management and bug tracking system, and Hudson for the continuous integration system. We do not stipulate a specific integrated development environment (IDE), although most of us use Eclipse and rely upon the code formatting and compile preferences to ensure no warnings or errors.

The rest of this chapter talks in more detail about these different tools and how to set them up. But first, we briefly describe our approach to development.

Rather than use a single formal development methodology, the ModeShape project incorporates those techniques, activities, and processes that are practical and work for the project. In fact, the committers are given a lot of freedom for how they develop the components and features they work on.

Nevertheless, we do encourage familiarity with several major techniques, including:

  • Agile software development includes those software methodologies (e.g., Scrum) that promote development iterations and open collaboration. While the ModeShape project doesn't follow these closely, we do emphasize the importance of always having running software and using running software as a measure of progress. The ModeShape project tries to release early and release often, with a goal of 4-6 weeks between releases.

  • Test-driven development (TDD) techniques encourage first writing test cases for new features and functionality, then changing the code to add the new features and functionality until the test cases pass, and refactoring the code as needed (when the tests all pass) to adapt to the newly adding functionality and to clean-up and address any duplication and inconsistencies.

  • Behavior-driven development (BDD) encourages developers to first list out the desired behaviors of the system first using words and phrases that are meaningful to users and observers of the system, then write tests that verify those behaviors, and finally change the code so that the system exhibits these behaviors and the tests pass. BDD helps get past one of the most difficult aspects of TDD: how do developers know what tests to write before they write the code? BDD focuses the developers on describing what the system should do and not do, and these can turn directly into tests. There are BDD frameworks available, but we've found that using JUnit 4.4 works very well for us. We first create our unit test method stubs using simple method names that describe what the component should (or should not) do, and treat these almost as requirements. For example, some test methods might be called shouldNotThrowAnErrorWhenStreamIsNull() or shouldReturnValueWithValidInputParameters(). Then it's easy to write the test method implementation, and follow that up with writing the actual component.

  • Lean software development is an adaptation of lean manufacturing techniques, where emphasis is placed on eliminating waste (e.g., defects, unnecessary complexity, unnecessary code/functionality/features), delivering as fast as possible, deferring irrevocable decisions as much as possible, continuous learning (continuously adapting and improving the process), empowering the team (or community, in our case), and several other guidelines. Lean software development can be thought of as an evolution of agile techniques in the same way that behavior-driven development is an evolution of test-driven development. Lean techniques help the developer to recognize and understand how and why features, bugs, and even their processes impact the development of software.

Currently, ModeShape is developed and built using JDK 6. So if you're trying to get ModeShape to compile locally, you should make sure you have the JDK 6 installed and are using it. If you're a contributor, you should make sure that you're using JDK 6 before committing any changes.

When installing a JDK, simply follow the procedure for your particular platform. On most platforms, this should set the JAVA_HOME environment variable. But if you run into any problems, first check that this environment variable was set to the correct location, and then check that you're running the version you expect by running the following command:

$ java -version

If you don't see the correct version, double-check your JDK installation.

ModeShape uses JIRA as its bug tracking, issue tracking, and project management tool. This is a browser-based tool, with very good functionality for managing the different tasks. It also serves as the community's roadmap, since we can define new features and manage them alongside of the bugs and other issues. Although most of the issues have been created by community members, we encourage any users to suggest new features, log defects, or identify shortcomings in ModeShape.

The ModeShape community also encourages its members to work only issues that are managed in JIRA, and preferably those that are targeted to the current release effort. If something isn't in JIRA but needs to get done, then create an issue before you start working on the code changes. Once you have code changes, you can upload a patch to the JIRA issue if the change is complex, if you want someone to review it, or if you don't have commit privileges and have fixed a bug.

ModeShape uses Subversion as its source code management system, and specifically the instance at JBoss.org. Although you can view the trunk of the Subversion repository directly (or using FishEye) through your browser, in order to get more than just a few files of the latest version of the source code, you probably want to have an SVN client installed. Several IDE's have SVN support included (or available as plugins), but having the command-line SVN client is recommended. See http://subversion.tigris.org/ for downloads and instructions for your particular platform.

Here are some useful URLs for the ModeShape Subversion:


When committing to SVN, be sure to include in a commit comment that includes the JIRA issue that the commit applies to and a very good and thorough description of what was done. It only takes a minute or two to be very clear about the change. And including the JIRA issue (e.g., "MODE-123") in the comment allows the JIRA system to track the changes that have been made for each issue.

Also, any single SVN commit should apply to one and only one JIRA issue. Doing this helps ensure that each commit is atomic and focused on a single activity. There are exceptions to this rule, but they are rare.

Sometimes you may have some local changes that you don't want to (or aren't allowed to) commit. You can make a patch file and upload it to the JIRA issue, allowing other committers to review the patch. However, to ensure that patches are easily applied, please use SVN to create the patch. To do this, simply do the following in the top of the codebase (e.g., the trunk directory):

$ svn diff . > ~/MODE-000.patch

where MODE-000 represents the ModeShape issue number. Note that the above command places the patch file in your home directory, but you can place the patch file anywhere. Then, simply use JIRA to attach the patch file to the particular issue, also adding a comment that describes the version number against which the patch was created.

To apply a patch, you usually want to start with a workspace that has no changes. Download the patch file, then issue the following command (again, from the top-level of the workspace):

$ patch -E -p0 < ~/MODE-000.patch

The "-E" option specifies to delete any files that were made empty by the application of the patch, and the "-p0" option instructs the patch tool to not change any of the paths. After you run this command, your working area should have the changes defined by the patch.

Several contributors are using Git on their local development machines. This allows the developer to use Git branches, commits, merges, and other Git tools, but still using the ModeShape Subversion repository. For more information, see our blog posts on the topic.

ModeShape uses Maven 2 for its build system, as is this example. Using Maven 2 has several advantages, including the ability to manage dependencies. If a library is needed, Maven automatically finds and downloads that library, plus everything that library needs. This means that it's very easy to build the examples - or even create a maven project that depends on the ModeShape JARs.

To use Maven with ModeShape, you'll need to have JDK 6 and Maven 2.0.9 (or higher).

Maven can be downloaded from http://maven.apache.org/, and is installed by unzipping the maven-2.0.9-bin.zip or maven-2.0.11-bin.zip file to a convenient location on your local disk. Then add $MAVEN_HOME/bin to your path.

While you're adding $MAVEN_HOME/bin to your path, you should also set the $MAVEN_OPTS environment variable to "-Xmx384m". If you don't do this, you will likely see an java.lang.OutOfMemoryError sometime during a full build.

The JBoss Maven repository provides a central location for not only the artifacts produced by the JBoss.org projects (well, at least those that use Maven), but also is where those projects can place the artifacts that they depend on. The new JBoss.org Maven repository uses the Nexus repository manager, and is configured to proxy other Maven repositories and automatically cache the third-party artifacts used in our builds. This helps ensure that developers have easy access to these artifacts (including sources) and that the project (and dependencies) can always be rebuilt when needed.

For more information about the JBoss Maven repository, see the announcement and documentation.

Note

Previous versions of ModeShape made use of the older JBoss.org Maven repository, and required modifying your local ~/.m2/settings.xml file. This is no longer required by users or contributors, since the ModeShape POM file is set up to reference the new JBoss.org repository.

However, if you are one of the ModeShape contributors that will be making and publishing ModeShape releases into the JBoss.org repository, you will need to modify your ~/.m2/settings.xml file to contain your JBoss.org repository credentials. For details, see the documentation for developers.

There are just a few commands that are useful for building ModeShape (and it's subprojects). Usually, these are issued while at the top level of the code (usually just below trunk/), although issuing them inside a subproject just applies to that subproject.

Table 2.2. Useful Maven commands

CommandDescription
mvn cleanClean up all built artifacts (e.g., the target/ directory in each project)
mvn clean installCalled the "quick build". Clean up all produced artifacts; compile the source code and test cases; run all of the unit tests; and install the resulting JAR artifact(s) into your local Maven repository (e.g, usually ~/.m2/repository). This is often what developers run prior to checking in changes, since it generally runs quickly. Note that no integration tests are performed, and HSQLDB is used when a database is needed.
mvn clean install -P integration This "integration build" does everything the "quick" build does plus compiling and running the integration tests, documentation, and examples, all of which add several minutes over the "quick build". Since the integration tests include running the JCR TCK tests against a variety of configurations with different connectors, this build should be run before committing changes to the JCR implementation code. Also, HSQLDB is used when a database is needed.
mvn clean install -Ddatabase=dbprofileSame as the "quick build", except that it specifies the database management system that is to be used by the tests. Options for "dbprofile" values are: "hsqldb", "h2", "postgresql_local", "postgresql8", "mysql5", "oracle9i", "oracle10g", "oracle11g", "db2v8", "db2v9", "sybase15", and "mssql2005". The database connection information for these database profiles are in the parent "pom.xml" file, and most of these are configured to use database instances within the JBoss Quality Assurance lab and are accessible only to Red Hat employees. However, feel free to add your own profiles or even change the settings in the POM file to suit your needs.
mvn clean install -Ddatabase=dbprofile -P integrationThis does the same as the "integration build", except that it specifies the database management system that is to be used by the unit and integration tests. Options for the "dbprofile" values are the same as listed above.
mvn clean install -P assemblyClean up all produced artifacts; compile the source code and test cases; run all of the unit tests; install the resulting JAR artifact(s); compile and run all integration tests; build the documentation; produce the JavaDoc; and build the ZIP assemblies for the source, binary distribution, documentation, JavaDoc, and examples. HSQLDB is used when a database is needed.

Warning

ModeShape clustering uses JGroups for communication between members of a cluster, and some of our unit and integration tests test this clustering capability. There are two common issues that you may run into when building and testing ModeShape.

Firstly, the JGroups configurations used in these tests attempt to use a network stack that supports both IPv4 and IPv6 addresses. However, these may fail (by the various engines failing to find other members in the cluster) if your machine is configured only for IPv4 or IPv6. We've defined two Maven profiles ("preferIpv4" and "preferIpv6") that you may need to use to say whether IPv4 or IPv6 (respectively) is preferred, and you can enable these on the Maven command line by adding "-PpreferIpv4" or "-PpreferIpv6". Of course, if your command already specifies other profiles, just combine the profile names with a comma (e.g., "mvn clean install -Pintegration,preferIpv4").

Secondly, as with all network communications, your firewall may be blocking incoming connections to Java. If test tests fail (again, where each engine fails to find other members in the cluster), check your firewall settings. Temporarily disabling your firewall and rerunning the tests may help determine if your firewall is involved.

ModeShape's continuous integration is done with several Hudson jobs on JBoss.org. These jobs run periodically and basically run the Maven build process. Any build failures or test failures are reported, as are basic statistics and history for each job.


Many of the ModeShape committers use the Eclipse IDE, and all project files required by Eclipse are committed in SVN, making it pretty easy to get an Eclipse workspace running with all of the ModeShape projects.

We're using either the Ganymede or Helios (latest) versions of Eclipse, available from Eclipse.org. Simply follow the instructions for your platform.

After Eclipse is installed, create a new workspace. Before importing the ModeShape projects, import (via File->Import->Preferences) the subset of the Eclipse preferences by importing the eclipse-preferences.epf file (located under trunk). Then, open the Eclipse preferences and open the Java->Code Style-> Formatter preference page, and press the "Import" button and choose the eclipse-code-formatter-profile.xml file (also located under trunk). This will load the code formatting preferences for the ModeShape project.

Then install Eclipse plugins for SVN, Maven, and optionally Git. (Remember, you will have to restart Eclipse after installing them.) We use the following plugins:


After you check out the ModeShape codebase, you can import the ModeShape Maven projects into Eclipse as Eclipse projects. To do this, go to "File->Import->Existing Projects", navigate to the trunk/ folder in the import wizard, and then check each of the subprojects that you want to have in your workspace. Don't forget about the projects under extensions/ or docs/.

This section outlines the basic process of releasing ModeShape. This must be done either by the project lead or only after communicating with the project lead.

Before continuing, your local workspace should contain no changes and should be a perfect reflection of Subversion. You can verify this by getting the latest from Subversion

$ svn update

and ensuring that you have no additional changes with

$ svn status

You may also want to note the revision number for use later on in the process. The release number is returned by the svn update command, but may also be found using

$ svn info

At this point, you're ready to verify that everything builds normally.

The version being released should match the JIRA road map. Make sure that all issues related to the release are closed. The project lead should be notified and approve that the release is taking place.

In this chapter, we described the various aspects of developing code for the ModeShape project. Next, we must discuss the testing practices for ModeShape project. This is the topic of the next chapter.