How to Contribute

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 will need the following tools to get a local copy of OpenMOLE running:
  • a java 8 or higher jdk (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
  • npm, required to build the website.
As a suggestion, we recommand the IntelliJ IDE to edit the Scala source code of the project.

First time setup πŸ”—

The following commands are to be typed in your command shell (prompt $> )
  1. Clone the OpenMOLE repository :
    $> git lfs install
    $> git lfs clone git@github.com:openmole/openmole.git
    
  2. Publish locally the content of the build-system and libraries subdirectory
  3. $> cd openmole/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 the openmole subdirectory.
$> cd openmole
$> sbt
# following commands occur inside sbt prompt
sbt:openmole-root> project openmole
openmole> assemble
Upon completion, the executable is placed under /openmole/openmole/bin/openmole/target/assemble and is launched as any executable via the ./openmole command. Then, the app should pop up in your default web browser, the URL should be 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 your 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 is hosted along the OpenMOLE documentation in the code repository. This 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/

Edit the website or the documentation πŸ”—

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, you need to have built a local copy of the website/documentation as shown above.
By default, website pages are located in openmole/openmole/bin/org.openmole.site/jvm/target/site/ Optionally you can use --test in order to verify the syntax of the scripts extracts in the documentation is valid. Bear in mind this is (really) time-consuming.
Sources for the documentation pages 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 stated by its name, 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 latest-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 the new features planned for this milestone are. This date is flexible and can be modulated given the progress of the new developments.

    Tips and tricks πŸ”—

    create a pull request πŸ”—

    To create a pull request, you would have to:
    • apply the first time setup of the openmole development environment
    • fork the repository of interest in github: use the fork button in the original repository and fork it into your own github account
    • add your fork as a remote repository
    • create a branch for you modifications, add your commits there, and push this branch to your github fork
    • from your github fork, create a pull request of your forked repository and branch into the dev branch of the openmole repository

    • error: You are not allowed to push code to this project πŸ”—

      First ensure you respect the contribution procedure and the branching model. You should not try to push directly to the openmole repository, but to your github fork of the repository instead.
      You can identify more precisely the git error by activating debug in the git command:
      $> GIT_TRACE=1 GIT_CURL_VERBOSE=1 git push <remote_repo> <branch_name>

      error: git-lfs [...] You are not allowed to push code to this project πŸ”—

      When pushing your updates to the fork, you might encounter this error:
      $> GIT_TRACE=1 GIT_CURL_VERBOSE=1 git push <remote_repo> <branch_name>
      13:50:17.630529 trace git-lfs: run_command: ssh -p 20022 -- git@gitlab.iscpif.fr git-lfs-authenticate openmole/openmole.git upload
      13:50:23.191218 trace git-lfs: ssh: git@gitlab.iscpif.fr failed, error: exit status 1, message: GitLab: You are not allowed to push code to this project.
      batch request: GitLab: You are not allowed to push code to this project.: exit status 1
      error: impossible de pousser des rΓ©fΓ©rences vers 'https://github.com/<your_username>/openmole.git'
      

      In this case, the push is failing when git lfs attempts to update the binaries referenced in the git repository into the ISCPIF gitlab. If you did not change the binaries, you might just skip that step by using command line:
      $> git push --no-verify <remote_repo> <branch_name>

      error: openmole compiles but fails at runtime because of a package not found πŸ”—

      Try a clean and complete rebuild:
      $> ./clean.sh
      [...]
      $> ./build.sh

      support for developers πŸ”—

      For developers support, remember you can get in touch with the community via:
      • the chat in channel "openmole-dev"
      • the OpenMOLE user forum