This page is dedicated to explaining 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).

Contribution procedure 🔗

When you want to contribute to the project (code or documentation) or if you've identified a bug in OpenMOLE, we recommend that you to start by submitting an @aa("issue", href := shared.link.issue), so that the community can identify the nature of the potential caveat. After that, you can send a pull request so that your potential changes can be discussed.

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

Everything about pull requests is explained on the help pages of GitHub.

Build the website 🔗

The source code of the website is hosted along the documentation in the OpenMOLE repository. Here's 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/grammar mistake/bad wording, or simply want to improve a part of the documentation you think is unclear. If so, you're more than welcomed to correct our mistakes and improve the documentation!
First, make your changes locally on your clone of the OpenMOLE repo, then check your changes by building the website as explained above. If everything works as it should and you're happy with your changes, send us a Pull Request on GitHub (all about pull requests here.
By default, website pages are located in openmole/openmole/bin/org.openmole.site/jvm/target/site/. Sources for the @b{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.

Organization of the OpenMOLE project 🔗

Repositories 🔗

OpenMOLE is made of three different projects:

• openmole/openmole the main project containing the source code for the core and plugins
• openmole/libraries 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 obviously, that's the build system :) It's very unlikely that you'll have to modify this project.

Branching model 🔗

OpenMOLE repos are divided into three main branches:

• dev contains the unstable, next version of the platform. It's our development branch. Disrupting features are developed in branches, branching off @code{dev}, and are merged back into dev as soon as they are working satisfyingly enough to be operational in the next release.
• #version-dev (e.g. 15-dev) is the stable, current version of the platform. It's a maintenance branch created to be able to patch the latest-released version. Hotfixes should be developed by branching off the corresponding version-dev branch and merged back into their upstream branch and master once working correctly.
• master is the main branch, from which the two former branches are derived.

The development version of the OpenMOLE website and software is compiled and distributed several times an hour at https://next.openmole.org/.
OpenMOLE applies a branching model derived from Vincent Driessen's. The advantage of this model is that new features are tested early in interaction with each other. 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 the new features planned for this milestone, and it is flexible and can be modulated given the progress of the new developments.

Tips and tricks 🔗

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.openmole.org git-lfs-authenticate openmole/openmole.git upload
13:50:23.191218 trace git-lfs: ssh: git@gitlab.openmole.org 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 the following on the 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 \"dev\"
• the OpenMOLE user forum