How can I contribute to OpEn?
Thank you for considering contributing to Optimization Engine (OpEn)!
OpEn is an open source project and welcomes contributions from the community.
You can contribute in several ways:
- Submit an issue:
Often bugs will go unnoticed by the core development team and certain
use cases and user needs will have evaded our attention.
Consider submitting an issue if:
- You would like to report a bug; please, use the provided template for reporting bugs. It is essential to give information about your system (OS, OpEn version) and outline a sequence of steps to reproduce the error. When possible, please provide a minimum working example
- You would like to request a new feature; please use the provided template
- You would like to propose modifications in OpEn's documentation, such as for some concepts to be better elucidated or a request for an additional example
- Share with us a success story on Discord
- Create a pull request (see below)
or, show us your love:
I just have a question!
You may also consult the frequently asked questions.
You may submit an issue regarding anything related to OpEn, such as:
- a bug
- insufficient/vague documentation
- request for a feature
- request for an example
You should, however, make sure that the same - or a very similar - issue is not already open. In that case, you may write a comment in an existing issue.
Contributing code or docs
In order to contribute code or documentation, you need to fork our github repository, make you modifications and submit a pull request. You should follow these rules:
- create one or more issues on github that will be associated with your changes
- take it from
master: fork OpEn and create a branch on
git checkout -b fix/xyz master
- read the style guide below (and write unit/integration tests)
- create a pull request in which you need to explain the key changes
Coding style guide
Things to keep in mind:
- Code: intuitive structure and variable names, short atomic functions,
- Comments: help others better understand your code
- Docs: document all functions (even private ones)
- Tests: write comprehnsive, exhaustive tests
Naming convention: We follow the standard naming convention of Rust.
Documentation: We follow these guidelines. Everything should be documented.
This documentation is generated with Docusaurus - read a detailed guide here.
- All docs are in
- Blog entries are in
To start the website locally (at http://localhost:3000/optimization-engine) change directory to
website and run
yarn start. To update the website, execute
./publish.sh (you need to be a collaborator on github).
When using Git, keep in mind the following guidelines:
- Create simple, atomic, commits
- Write comprehensive commit messages
- Work on a forked repository
- When you're done, submit a pull request to
alphaville/optimization-engine; it will be promptly delegated to a reviewer and we will contact you as soon as possible.
master is protected and all pull requests need to be reviewed by a person
other than their proposer before they can be merged into
This project consists of independent modules:
(i) the core Rust library,
(ii) the MATLAB interface,
(iii) the Python interface.
Each module has a different version number (
We use the SemVer standard - we quote from semver.org:
Given a version number
MAJOR.MINOR.PATCH, increment the:
MAJORversion when you make incompatible API changes,
MINORversion when you add functionality in a backwards-compatible manner, and
PATCHversion when you make backwards-compatible bug fixes.
Additional labels for pre-release and build metadata are available as extensions to the
We also keep a log of changes where we summarize the main changes since last version.
Each time the major or minor number of the Rust library is updated, a new crate should be published on crates.io.
In order to release a new version make sure that you have done the following:
- Updated CHANGELOG
- Updated the version in (SemVer):
- Resolved all associated issues on github (and you have created tests for these)
- Updated the documentation (Rust/Python API docs + website)
- Merged into master (your pull request has been approved)
- All tests pass on Travis CI and Appveyor
Cargo.toml(set it back to
opengenon PyPI (if necessary)
- before doing so, make sure that the cargo.toml template points to the correct version of OpEn
- Changed "Unreleased" into the right version in CHANGELOG and created a release on github (example release v0.4.0)