How to Contribute
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 -versionin a terminal
- the git software and the LFS extension
- sbt, the scala building tool
- npm, required to build the website.
First time setup 🔗The following commands are to be typed in your command shell (prompt $> )
Clone the OpenMOLE repository :
$> git lfs install $> git lfs clone email@example.com:openmole/openmole.git
Publish locally the content of the
$> cd openmole/build-system $> sbt publishLocal $> cd ../libraries/ $> sbt publishLocal
Build from Sources 🔗To build the OpenMOLE application, use the
sbt assemblecommand inside the openmole subdirectory.
Upon completion, the executable is placed under
$> cd openmole $> sbt # following commands occur inside sbt prompt sbt:openmole-root> project openmole openmole> assemble
/openmole/openmole/bin/openmole/target/assembleand is launched as any executable via the
./openmolecommand. Then, the app should pop up in your default web browser, the URL should be something like
Standalone archive 🔗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
$> 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.
Once sbt is launched, use the
$> cd openmole/openmole $> sbt
buildSitecommand inside sbt to build the webpages. Location of the generated pages can be set via the
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
--testin 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/openmoleThey are written using scalatex, a DSL to generate html content.
Repositories 🔗OpenMOLE repos are divided into three branches.
devcontains the unstable, current version of the platform.
#version-deve.g. 7-dev , is the stabilized version of the
masteris 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:
Tips and tricks 🔗
create a pull request 🔗To create a pull request, you would have to:
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 -- firstname.lastname@example.org git-lfs-authenticate openmole/openmole.git upload 13:50:23.191218 trace git-lfs: ssh: email@example.com 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