How To contribute to the OpenMOLE project

Contents
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.

Prerequisites


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.

First time setup


  1. Clone the OpenMOLE repository :
    git lfs clone git@github.com:openmole/openmole.git
    
  2. Set the git submodules inside the openmole subdirectory
  3. cd openmole
    git submodule update --init --remote
    
  4. Publish locally the content of the build-system and libraries subdirectory
  5.  cd build-system
    sbt publishLocal
     cd ../libraries/
    sbt publishLocal
    
These commands may take some time (a few minutes at least).

Build from Sources


To build the OpenMOLE application, use the sbt assemble command inside openmole subdirectory.
cd openmole
sbt assemble
Upon completion, the executable is placed under /openmole/openmole/bin/openmole/target/assemble and is launched as any executable : ./openmole Then, the app should pop up in your default web browser, the URL is something like http://localhost:44961/app

Standalone archive


You can create a standalone archive of your fresh OpenMOLE build and ship it around by using the task openmole:tar:
sbt openmole:tar

You will find the resulting archive in bin/openmole/target/openmole.tar.gz.

Publish the bundles

cd build-system
sbt publish
cd ../libraries
sbt publish
cd ../openmole
sbt publish

Compile within Docker


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
cd docker-build
./run -v /a/local/path/on/your/system
# You should be in the docker container now, execute
clone
compile

You can now find the compile OpenMOLE in /a/local/path/on/your/system/openmole/openmole/bin/openmole/target/assemble/

Build the website


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.
cd openmole/openmole
sbt
Once sbt is launched, use the buildSite command inside sbt to build the webpages. Location of the generated pages can be set via the --target option, e.g.
buildSite --target /tmp/

By default, pages are located in openmole/openmole/bin/org.openmole.site/jvm/target/site/ 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 --no-test 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 using --no-market-test.

Edit Documentation pages


Sources are located in openmole/openmole/bin/org.openmole.site/jvm/src/main/scalatex/openmole They are written using scalatex, a DSL to generate html content.

Repositories


OpenMOLE repos 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 dev branch
  • master is the main branch, from which the two former branches are derived

Project organization


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.

Dev versions


The development version of the OpenMOLE site and software is compiled and distributed several times an hour at https://next.openmole.org/.

Bug Report


Please report bugs you may find in OpenMOLE on the bug tracker.

Contribution procedure


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.

Branching model


OpenMOLE applies a branching model derived from Vincent Driessen's. Some slight differences should be noted:
  • 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.
  • 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.