How To contribute to the OpenMOLE project
This page is dedicated to explain the organization of the project, the tools you need and the procedures to follow if
you want to contribute painlessly to the OpenMOLE project (software and documentation).
It also explains the various versions of OpenMOLE you may want to use/deploy, from local desktop to distant server.
You need three tools installed to get a local copy of OpenMOLE:
A java 8 jdk or higher (N.B. not only the JRE). Check your version by typing
javac -version in a terminal
the git software and the LFS extension
sbt , the scala building tool
As a suggestion, we recommand the IntelliJ IDE
to edit the scala source code of the project.
Clone the OpenMOLE repository :
git lfs clone email@example.com:openmole/openmole.git
Set the git submodules inside the openmole subdirectory
git submodule update --init --remote
Publish locally the content of the
These commands may take some time (a few minutes at least).
To build the OpenMOLE application, use the
command inside openmole subdirectory.
Upon completion, the executable is placed under
and is launched as any executable :
Then, the app should pop up in your default web browser, the URL is something like
You can create a standalone archive of your fresh OpenMOLE build and ship it around by using the task openmole:tar
You will find the resulting archive in bin/openmole/target/openmole.tar.gz
Publish the bundles
An easy way to get an OpenMOLE compilation environment up and running is to use docker. Once docker is installed on you machine you can do:
git clone https://github.com/openmole/docker-build.git
./run -v /a/local/path/on/your/system
# You should be in the docker container now, execute
You can now find the compile OpenMOLE in /a/local/path/on/your/system/openmole/openmole/bin/openmole/target/assemble/
The source code of the website and the OpenMOLE documentation are hosted along in the code repository.
You might spot a typo/incorrect spelling/grammar mistake/bad wording or simply want to improve a part of the
documentation you think is unclear.
If so, you're more than welcome to correct our mistakes and improve the documentation. To check your changes locally before sending us a Pull Request, here is how to build a local copy of the website/documentation.
Once sbt is launched, use the
command inside sbt to build the webpages.
Location of the generated pages can be set via the
buildSite --target /tmp/
By default, pages are located in
Updating the git submodules is mandatory the first time
you set up your OpenMOLE development environment.
It pulls the examples from the market place
that are necessary to build the documentation website.
Optionally you can use
in order to disable the tests of the scripts, which
is (really) time-consuming. The tests concerning the examples from the OpenMOLE market can in turn be disabled
Sources are located in
They are written using scalatex
, a DSL to generate html content.
are divided into three branches.
dev contains the unstable, current version of the platform.
#version-dev e.g. 7-dev , is the stabilized version of the
master is the main branch, from which the two former branches are derived
OpenMOLE is made of three different projects:
- openmole/openmole: the main project containing the source code for the core and plugins
- openmole/libraries: contains the libraries which OpenMOLE depends on but are not available as OSGi bundles from their developers. This project takes all these dependencies, wraps them in OSGi projects and generates the corresponding bundles to be later imported by OpenMOLE's main project.
- openmole/build-system: As its name stands, that's the build system :) It's very unlikely that you'll have to modify this project.
The development version of the OpenMOLE site and software is compiled and distributed several times an hour at https://next.openmole.org/
Please report bugs you may find in OpenMOLE on the bug tracker
When you want to contribute to the project (code or documentation) we recommend that you to start by submitting an issue
, so that the community can identify the nature of the potential caveat.
After that, send a pull request
so that your potential changes can be discussed.
The next version of OpenMOLE is in the dev branch, it's our development branch;
Disrupting features are developed in branches, branching off dev;
New features are merged into the dev branch as soon as they are working satisfyingly enough to be operational in the next release;
With each release, a maintenance branch is created to be able to patch the last released version, this branch is called version-dev. These are the so-called stable branches for each release;
Hotfixes should be developed by branching off the corresponding version-dev branch and merged back into their upstream branch and master.
OpenMOLE applies a branching model derived from Vincent Driessen's
. Some slight differences should be noted:
The advantage of this model is that new features are tested early in interaction with each others. This scheme serves an hybrid, date-based/feature-based release schedule.
At the beginning of a development cycle, an approximate date is given for the next release. This date depends on what are the new features planned for this milestone. This date is flexible and can be modulated given the progress of the new developments.