Skip to main content

Contributing to OpEn

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:

Star

I just have a question!​

The easiest and quickest way to ask a question is to reach us on Discord or Gitter.

You may also consult the frequently asked questions.

Submitting issues​

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 master
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

Rust​

General guidelines: Read the Rust API guidelines and this API checklist

Naming convention: We follow the standard naming convention of Rust.

Documentation: We follow these guidelines. Everything should be documented.

Python​

We follow this style guide and its naming convention

Website​

This documentation is generated with Docusaurus - read a detailed guide here.

  • All docs are in docs/
  • Blog entries are in website/blog/

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

Using Git​

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.

Branch master is protected and all pull requests need to be reviewed by a person other than their proposer before they can be merged into master.

Versioning​

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 (X.Y.Z).

We use the SemVer standard - we quote from semver.org:

Given a version number MAJOR.MINOR.PATCH, increment the:

  • MAJOR version when you make incompatible API changes,
  • MINOR version when you add functionality in a backwards-compatible manner, and
  • PATCH version when you make backwards-compatible bug fixes.

Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.

We also keep a log of changes where we summarize the main changes since last version.

Releasing​

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
  • Set publish=true in Cargo.toml (set it back to false for safety)
  • Publish opengen on 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)