Chapter 23. Getting Started as a Developer

This chapter describes the basic steps to get started as a developer for the OpenEngSB project.

23.1. Getting comfortable with the infrastructure

As any open source project the OpenEngSB development depends on a wide range of different infrastructural and communication methods to get things done. The following sub-chapters describe the different tools, their location and usage in the OpenEngSB development process.

23.1.1. Mailing Lists

The most important communication medium for the OpenEngSB development team is email. Mostly all of the vital design, architectural and infrastructural decisions are discussed on the OpenEngSB developer list. Therefore, the first step to get involved into the development of the OpenEngSB is to register to the Google Groups OpenEngSB Developer Mailing List and say hello world.

While notifications from the Hudson Build Server, about code commits and Jira issues are vital for the OpenEngSB core developer, they may not be as interesting for you. If you get annoyed by the automatically generated notification mails ignore all mails from openengsb@gmail.com and noreply@github.com to openengsb-dev@googlegroups.com. Please remember it is important to configure both, to and from in your filter. Both addresses will also send notifications directly to you which are important and should not be ignored!

23.1.2. Jira Issue Tracker

All issues are stored within a Jira instance reachable at issues.openengsb.org. Please use the issue tracker to keep track of all bugs, ideas and new features you're currently working or of which you think they might be interesting.

23.1.3. Code Repository

As for any open source project the source code is public available. We've chosen Github for this task. The project is available at github.com/openengsb/openengsb.

As explained later within this document Github is not only used to store our code, but also for collaboration, code review and patch-tracking.

23.1.4. Maven Repository

The OpenEngSB is available at Maven Central. We still have our own Maven repository at maven.openengsb.org/ and snapshots are available via the sonatype Maven repository at http://oss.sonatype.org.

23.1.5. Build Server

The master and integration branch of the OpenEngSB repository are watched and built by a Hudson build server instance available at build.openengsb.org. Notifications about failures are directly sent to the OpenEngSB developer list.

23.2. Prerequisites

First of all the latest JDK has to be installed on the system and the JAVA_HOME variable has to be set accordingly. All further steps are described in the subsections of this chapter.

23.2.1. Installing Git

It is assumed that Git is installed. For Linux your distribution provides already a package for git. Please use the package manager of your distribution (apt, yum, pacman, ...) to install it. For MAC binaries are available at git-scm.com. For MS users cygwin or msysgit. After installing, set at least the following variables:


        git config --global user.name "Firstname Lastname"
        git config --global user.email user@example.com
        git config --global core.autcrlf input
      

23.2.2. Installing Maven

Finally download Apache Maven3 and unpack it. Add the path of the maven binary to your PATH variable. Furthermore you should set the MAVEN_OPTS environment variable to allow Maven to use more RAM. If you don't you'll get Out Of Memory errors.


          export PATH=$PATH:/path/to/maven/bin
          export MAVEN_OPTS='-Xmx1024M -XX:MaxPermSize=512m'
        

Add these commands to ~/.bashrc to make the settings permanent.

23.3. Starting OpenEngSB

The next step is to get the OpenEngSB source by checking out the current master using git:


      git clone git://github.com/openengsb/openengsb.git
    

Now start the OpenEngSB by executing


      mvn clean install pax:provision
    

This command builds, tests and runs the OpenEngSB right from your command-line. Executing the following command will shutdown it again:


      shutdown
    

23.4. Using Eclipse

Eclipse had been chosen by the OpenEngSB team as the main development environment. After checkout the code the following command creates the required Eclipse project files:


      mvn install
      mvn eclipse:eclipse
    

Start Eclipse and select any workspace. The folder eclipse-workspace is ignored in the OpenEngSB project structure for this purpose. But you can choose any other directory if you prefer. At the preference page go to Java/Build Path/Classpath Variables and create a new M2_REPO pointing to ~/.m2/repository. Now use File, Import..., Existing Projects into Workspace. As the root directory select the root of the OpenEngSB source. Eclipse will list several projects and for now it's best to import them all by clicking Finish.

At openengsb/etc/eclipse/ eclipse configuration files for formatting and Checkstyle can be found. These files should be used.

23.5. Using Other IDEs than Eclipse

Basically, the OpenEngSB is developed in plain Java, which means any other IDE than Eclipse can be used too. While there are tools for most IDEs to use Checkstyle, but non of it supports the formatting file of the OpenEngSB. Please use Checkstyle, which automatically validates the eclipse formatting rules too.

23.6. Git Documentation

23.6.1. Usage

First of all this chapter explains only the very basics of Git and only that parts directly relevant for the development of the OpenEngSB project, but not the entire idea and possibilities of Git. Please read some tutorials first to get how to work with Git and see this chapter more as an summary! You may also take a look at the Git Documentation Page and the Pro Git Book.

23.6.2. Github

OpenEngSB is developed at github.com. Please create an account there and explore its features. Specify your real name in the admin tab and add a picture. This makes it easier to associate your commits to you.

23.6.3. Starting up and configure

Before starting to work with Git some settings should be applied to Git. Therefore simply execute the following commands.

git config --global user.name "Firstname Lastname"
git config --global user.email user@example.com
git config --global color.ui "auto"
git config --global pack.threads "0"
git config --global diff.renamelimit "0"
git config --global core.autocrlf "input"

Additionally execute the special settings for github as could be found on github in the "Account Settings" tab is a point "Global git config information". Please use the two git commands described there

git config --global github.user username
git config --global github.token token

If you don't already have an SSH key you can create one by executing ssh-keygen Simply answer all questions from the application with "enter" without enter any values. Afterwards the content of the id_rsa.pub file from your ~/.ssh/ directory should be submitted to github (Account Settings/SSH public keys).

23.6.4. Contributor Workflow

Contributor are all developer who like to contribute to the OpenEngSB project, but not have commit rights to openengsb/openengsb.

Please keep in mind, that this manual is NOT a Git tutorial. Github itself, e.g. provides a great help at help.github.com. All base concepts such as forking, pull-requests, ...

Please start by choose or create a new issue. Now create a new fork of the OpenEngSB at Github (if you've not done already so; otherwise this is explained here). Clone your fork, but also add the original openengsb repository as remote repository. This is also explained here. In difference to the Github tutorial please do not commit to the master, but rather create a new branch named OPENENGSB-ISSUE_NUMBER_YOURE_WORKING_ON. Optionally append /DESCRIPTION (e.g. OPENENGSB-586/mvn-eclipse-download-fix).

git checkout -b OPENENGSB-ISSUE origin/BRANCH

BRANCH is the point where you like to start your work. If you like to contribute to the head this will be typically integration, but could also be a commit or a complete different branch. This is the OpenEngSB schema for naming branches and we'll really appreciate if you work according to it.

Now hack, commit and push as you like. If you think you're finished execute the etc/scripts/pre-push.sh script validating your code, tests, licenses and so on. If everything works without errors create a Github pull request on Github, between the master or integration branch (depending on where you've created your branch on) and your branch. This process is also explained at help.github.com (here). In addition it will help if you add the link to the pull request to the issue you're working on. A commiter will tend as fast as possible to your request and give feedback or directly merge your commit into the integration/master branch.

23.6.5. Commiter Workflow

The only difference between a commiter and a contributor is that he has to watch and merge branches of contributors. If a commiter is happy with the work of a contributor. Comments and other discussions should be done on the mailing list and/or via the Github review system and pull requests.

In addition commiters typically do not create forks but rather create their branches directly in the OpenEngSB repository. This is done because the repository is covered by the OpenEngSB build server and in addition keeps everything closer together.

23.6.6. Additional Rules

  1. (Contributor/Committer) All development is done in branches (also of the core developers) One exception to this rule exists: Small fixes and maintenance work which is NOT related to a new feature and does not exceed 2 commits should be cherry-picked into the master directly.

  2. (Contributor/Committer) Rebase is not dead (although we use merges). Never ever commit local merges. You still should develop in local dev branches and rebasing them with the upstream branches. Only if nobody else has access to your fork you can be sure that nobody changed it!

  3. (Committer) If merging branches from forked repositories ALWAYS use the --no-ff option for merges; this will always create a merge node (even if a fast-forward merge is possible). This is required to create a clear and consistent history!

  4. Avoid backward merges from the master and keep feature branches small! This does not mean that backward merges from master are forbidden. But they should not be done too often, since they create a history not easy to read. Please use the method described on this page (with --no-ff --no-commit) to reduce the number of merge nodes.

  5. Use meaningful feature branch names. Using the merge history in the master you can easily follow the development of features. But this requires (maybe long) good names! In addition, always start with OPENENGSB-NUMBER of the issue you're working on. Try to always do work based on issues. If no issue covers what you're doing create one.

23.7. Useful Tools

23.7.1. openengsb-maven-plugin

The openengsb-maven-plugin is a plugin for Apache Maven, intended to simplify various activities (creating domains or connectors, building a release artifact of the whole project etc.) when developing for the OpenEngSB. It is automatically installed into your local maven repository when doing a mvn clean install of the whole project for the first time. You can also install the plugin separately by invoking mvn clean install within tooling/openengsb-maven-plugin/.

The plugin can be invoked by mvn org.openengsb.tooling.pluginsuite:openengsb-maven-plugin:<version>:<goal> where version is the current version of the OpenEngSB and goal denotes the mojo you want to execute.

If the current version is no SNAPSHOT version, you can abbreviate this long command by following configuration:

Create ~/.m2/settings.xml with the following content:

      <?xml version="1.0" encoding="UTF-8"?>
      <settings xmlns="http://maven.apache.org/settings/1.0.0" 
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
        <pluginGroups>
          <pluginGroup>org.openengsb.tooling.pluginsuite</pluginGroup>
        </pluginGroups>
      </settings>
    

With this configuration above the plugin can be invoked by mvn openengsb:<goal>. But note that this will only work if a non-SNAPSHOT version is available.

23.7.1.1. Goals

assemble

Installs the OpenEngSB. Is equivalent to executing mvn install -Prelease,nightly -Dmaven.test.skip=true

genConnector

Guides interactively through the creation of a connector and generates the artifact via the connector archetype. For additional info how to create a connector see Chapter 24, How To Create an Internal Connector

genDomain

Guides interactively through the creation of a domain and generates the artifact via the domain archetype. For additional info how to create a domain see Chapter 25, How To Create an Internal Domain

licenseCheck

Performs a check if appropriate license headers are available in every source file. The licenseCheck mojo wraps the com.mycila.maven-license-plugin. A large part of the default behavior of this mojo can be changed in tooling/openengsb-maven-plugin/src/main/resources/licenseMojo/licenseCheckConfig.xml. See this site for available configuration options. The openengsb-maven-plugin needs to be reinstalled after changing its default behavior.

licenseFormat

Adds a license header to files where the license header is missing. A large part of the default behavior of this mojo can be changed in tooling/openengsb-maven-plugin/src/main/resources/licenseMojo/licenseFormatConfig.xml. See this site for available configuration options. The openengsb-maven-plugin needs to be reinstalled after changing its default behavior.