This chapter describes the basic steps to get started as a developer for the OpenEngSB project.
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.
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!
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.
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.
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.
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.
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.
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
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.
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
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 and create a new M2_REPO pointing
to ~/.m2/repository
. Now use , ,
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 .
At openengsb/etc/eclipse/
eclipse configuration files for formatting and Checkstyle can be found.
These files should be used.
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.
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.
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.
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).
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.
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.
(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.
(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!
(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!
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.
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.
The maven-openengsb-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/maven-openengsb-plugin/
.
The plugin can be invoked by
mvn org.openengsb.tooling.pluginsuite:maven-openengsb-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.