Version 16
Created by rhauch on Dec 24, 2010 12:01 PM. Last modified by rhauch on Dec 1, 2011 11:07 AM.
    The ModeShape project uses a number of tools, and procedures to assist in the development of
    the software. This chapter describes what these and how we use them. We'll start by going over the
    general practices that we tend to follow, and then we'll describe our toolset and describe how
    you can set up your development environment.

     

    See also: ModeShape and Maven  ModeShape Development Workflow ModeShape Development Guidelines

     

     

     

    The ModeShape project uses a number of tools to build, maintain, deploy, test, and run our software. A few of these are mandatory, because the whole community uses them. But we try to place fewer restrictions on the tools developers use locally, because we all have our own preferences.

     

     

    JDK

    Currently, ModeShape is developed and built using JDK 6. 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. 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.

     

    JIRA

    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 a proposed bug fix.

     

    You will get an account for our JIRA when you sign up for a JBoss.org account (see below).

     

    Git

    ModeShape source code is managed within Git, and our authoritative repository is currently hosted on GitHub. Git is a fast and efficient distributed version control system (DVCS), which means that every clone is a full mirror of the repository containing the complete history of the code and all revision tracking capabilities.
    Our use of Git is relatively new, but it offers significant advances over other version control systems like Subversion.
    • Support for non-linear development acquisition, which means that branches are cheap and easy to create, and can be easily merged onto multiple other branches. So, it's very easy to create a branch for each JIRA issue, and then merge the changes for that issue onto one or more release branches. We'll talk more about topic branches later on.
    • Git is distributed, meaning every instance (or "clone") of the repository is a complete copy, and Git makes it easy to push and pull changes between repository instances. So each developer has a complete, local history of the entire ModeShape source code. But because Git is so efficient, a full local clone of the ModeShape repository actually takes less disk space than a single checkout from Subversion. (This is because a Subversion checkout contains two copies of every file: one that you work with and one in the ".svn" directory.) Git also allows developers to make local commits and see version history even when disconnected from the network. Once connected, these commits can be pushed to other repositories.
    • Strong authenticated history means that every Git commit is dependent upon all prior development history, and every commit is uniquely identified by a secure hash of its contents. These identifiers mean its not possible to change a version of the code without the identifier changing. Plus, these identifiers make it easy for a repository instance to know whether it's already seen a particular commit - two changesets with the same identifier are indeed the same commit.
    • File renames and moves are tracked implicitly because Git tracks snapshots of the entire directory structure. Git detects renames not when taking snapshots but when comparing histories, meaning renames and moves can be discovered and identified at any time between any points in time.
    • Using multiple remote repositories is easy, because Git is inherently distributed. This means that while each developer has their own local Git repository, then can interact with multiple remote repositories. For example, each developer might also have a public GitHub repository (which is a fork of the authoritative repository), and it is here they can push their changes to share with others before they are merged into the authoritative codebase, yet they can also easily pull changes from the authoritative repository. The ability to easily work with multiple remote repositories opens up all kinds of possibilities for collaboration that were simply not possible with a centralized version control system.
    • Git metadata doesn't pollute the directories, making it easy to use your operating system and other tools without stepping on or seeing the metadata. All Git information is stored within a single ".git" directory at the top of the directory structure. (Remember how Subversion littered your working area with ".svn" directories, and how removing or moving them wreaked havoc with Subversion? No more with Git!)

     

    If you're not familiar with Git, this may sound intimidating. Sure, it will take a little getting used to at first, but once you learn what it lets you do, you'll start to wonder how you got work done before you used Git!

     

    We've captured recipes for using Git on the ModeShape Development Workflow page. But we suggest reading Scott Chacon's excellent Pro Git book. It's packed full of great information and it's available for free online (although buying a printed copy will help support the site).

     

    GitHub has some of the best instructions for installing Git, which even redirect based upon your operating system. Be sure to configure your Git installation with your name and email address:

     

     

    
$ git config --global user.name "John Doe"
$ git config --global user.email "john.doe@example.com"

     

    We also suggest looking at some other productivity enhancements. For example, there is an auto-completion script that will make the command-line show auto-completion options for branches, tags, remotes, and other parameters.

    GitHub

    The official Git repository for ModeShape is on GitHub.com at https://github.com/ModeShape/modeshape. If you want to get the source code, you can clone this using the read-only URL. However, if you want to contribute in any way, we suggest forking the official repository, push your changes to your public fork, and generating pull requests. This entire procedure is described on the ModeShape Development Workflow page.
    This pull-request feature is unique to GitHub, and provides a formal code review tool where our community can propose, discuss them, and even add line notes. But GitHub is also very usable.
    To set up your GitHub account, simply follow the instructions on GitHub's help system. Be sure to add to your GitHub account the email address that you used when configuring Git above.

    JBoss.org

    If you don't already have a JBoss.org account, sign up for one so that you can add issues to JIRA, post in our forums, and create or edit articles in our wiki. It's pretty easy, and of course free. Before we can accept your changes to the codebase, we also require that you sign a contributor agreement for ModeShape (even if you've already signed a contributor agreement for other projects hosted at JBoss.org).
    We can also associate your commits on GitHub with your JBoss.org account (for JIRA and Fisheye) if you update your JBoss.org profile with your GitHub and Git author name.
    To do this, go to http://jboss.org, choose "Login" from the very top of the page, click on "Your Stuff" and choose "Profile", and click on the "Edit profile & privacy" link in the right-hand column. (See http://www.jboss.org/help/userprofile.html for more detailed instructions and screen shots.) The "Edit Profile" tab will have a form with lots of fields, and you will need to update two of them:

     

    • "github Username" - enter your login name for your GitHub.com account
    • "Git author names" - enter the user.name value used in your Git config; can be a comma-separated list if you use different values in different Git repositories.

     

    Then save the changes to your profile.

    Maven

    ModeShape uses Maven 3 for its build system (as of Feb 22, 2010). Using Maven 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.

     

    ModeShape requires Maven 3.0.1 (or later). Installing is easy:

     

    1. Download an installation from http://maven.apache.org/
    2. Unzip (or untar) the downloaded file to a convenient location on your local disk (e.g., /usr/local)
    3. Add $MAVEN_HOME/bin to your path
    4. Set the $MAVEN_OPTS environment variable to "-Xmx384m -XX:MaxPermSize=512m".  (If you don't do this, you will likely see an java.lang.OutOfMemoryError sometime during a full build.)

     

    The ModeShape source code contains the Maven POM files that dictate how the builds work, and they are already configured to use the JBoss Maven repository. The 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.

     

    For details on how to build ModeShape with Maven, see the ModeShape and Maven document.

    Hudson

    ModeShape's continuous integration is done with several Hudson jobs on JBoss.org. Several of the lead developers (that work for Red Hat) configure and maintain these Hudson jobs to periodically run various Maven builds (see below). Any build failures or test failures are reported to the developers mailing list.

     

    • The Continuous job polls Git every 15 minutes and runs a full integration build when new commits are seen.
    • The Nightly job runs a full integration build every night (usually around 2 a.m. EDT), regardless of whether changes have been committed to the official Git repository since the previous night.
    • The JCR 2.0 API Compatibility runs every night (usually around 2 a.m. EDT), regardless of whether changes have been committed to the official Git repository since the previous night. This job runs a full integration build plus all of the JCR TCK unit tests, and may have several failures.

     

    Eclipse IDE

     

    Many of the ModeShape committers use the Eclipse IDE, and all project files required by Eclipse are committed into Git, 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 and you have a cloned Git repository, create a new workspace. Many of us create our workspace in the same location as your local Git repository (that is, in the directory containing the ".git" directory). But there are a few things to do before importing the ModeShape code.

     

    First, import (via File->Import->Preferences) the subset of the Eclipse preferences by importing the "eclipse-preferences.epf" file (located at the top level of the source). Then, open the Eclipse preferences and the Java->Code Style-> Formatter preference page, and press the "Import" button and choose the "eclipse-code-formatter-profile.xml" file (also located under at the top level of the source).  This will load the code formatting preferences for the ModeShape project.

     

    Second, install Eclipse plugins Maven and Git. Remember, you will have to restart Eclipse after installing them. Here are the details for these plugins:

     

     

    Now you can import the ModeShape Maven modules into Eclipse as Eclipse projects. To do this, go to File->Import->Maven->Existing Maven Projects, in the second step of the wizard select the root directory of your modeshape source code (i.e., the same folder which has the .git folder), and follow the wizard and check each of the subprojects that you want to have in your workspace. (There's no need to include the projects under the sandbox/ folder, as they likely won't compile anyway.

     

    To enable the git Team features on the project, select the projects list and right-click. Select the menu item Team -> Share Project. In the wizard select Git as the repository type. Finally click finish to enable the git features on the projects.

     

     

    IRC

     

    We use the #modeshape chat room on irc.freenode.net extensively for real-time discussions between the contributors and to help out and answer the questions of our users. The real-time nature of IRC is really invaluable for a distributed team. We've integrated our GitHub account, so all commits to the official repository are sent to our chat room. Plus, we have a bot that does a number of useful things, including looking for JIRA issue numbers (e.g., "MODE-1234") and print out in the room a summary of the issue. We've even talked about using it for regular online meetings.

     

    There are a number of IRC clients around, and we really don't care which one you pick. IRC clients with some form of notifications are nice to have, since we often address who we're talking to by prefixing messages with usernames.