Home
We welcome contributions to libRoadRunner. libRoadRunner is licensed under version 2.0 of the Apache license. Any contributions you submit to the project must be licensed under the Apache 2.0 license.
This page contains the contribution guidelines for libRoadRunner. Contibutors are responsible for complying with the guidelines, including (but not limited to) making commits to the correct branch. Maintainers are not responsible for changes made to the wrong branch. Contributors take full responsibility for ensuring that their changes get merged into the develop branch. Contributors must work with maintainers to ensure their changes get merged in before deadlines.
The develop branch of libRoadRunner is used as the main development branch. The master branch is reserved for releases, in order to make the master branch more stable. When a new release is drafted, the changes from develop are merged into master.
Only core developers (Kyle, Kiri, Lucian, Herbert) should push directly to develop. Everyone else should push to a feature branch and submit a pull request for develop.
libRoadRunner uses Travis CI. After each commit to develop, Travis automatically clones and builds the entire project from scratch in a dedicated VM. Travis also runs libRoadRunner's test suite, which includes Python and C++ unit tests as well as the SBML test suite. If any if these tests fail, Travis will report the failure via an email message sent to the libRoadRunner mailing list.
Contributors are responsible for ensuring that their contributions do not break the build. Changes that break the build are subject to reversion.
If you think a change might break the build, you can push the change to a feature branch and open a pull request from the feature branch into develop. Travis will automatically build and test the pull request, preventing potentially hazardous changes from being committed to develop.
The most important part of coding is that it must be readable and understandable. Someone new to the code should, with reasonable effort be able understand what is going on. Remember that source code is for humans to read, not just computers. See maintenance for tips.
libRoadRunner uses CTest to automatically run unit tests for each release and via Travis for each commit to develop. These tests include:
- A performance regression benchmark based on the Bioinformatics paper (http://bioinformatics.oxfordjournals.org/cgi/content/full/btv363?ijkey=ZlXgBJdNDjW4s6e&keytype=ref)
- The Python unit test suite
- The C++ unit test suite (includes the SBML test suite)
The release protocol for libRoadRunner consists of
- Ensuring all integration tests pass on all platforms (Windows, OS X, Linux)
- Incrementing the version number in the root CMakeLists.txt and wrappers/Python/docs/conf.py in develop
- Updating the changelog in the Debian packager
- Merging the develop branch into master via a pull request
- Creating a GitHub release tag (be sure to select master as the target branch)
libRoadRunner uses CMake as a cross-platform build system. We use the Visual Studio 2013 generator on Windows, the XCode generator on Mac OS X, and the Unix Makefiles generator on Linux.
libRoadRunner is designed to support Mac OS X and Windows, and binaries should always be provided for these platforms for each release.
Reduce maintenance costs whenever possible.
It is important to write code so that it is easy to maintain:
Avoid writing clever code that only you could possibly understand. Avoid writing code that is at the bleeding edge of a technology. Only use dependencies that are absolutely critical to the project.
In addition:
Comment your code - but don’t comment the obvious, eg
time = 0; // Initialize time to zero
Use sensible names for variables
Documentation should always be provided for any changes to the libRoadRunner C++ sources via Doxygen tags. For changes to language bindings, the language's respective documentation system should be used. For example, changes to libRoadRunner's Python API should include changes to the Sphinx documentation in wrappers/Python/docs.