Contribution Guide¶
Filing a bug report or feature request¶
Via GitLab¶
If you have a GitLab account, just head to PICOS’ official issue tracker.
Via mail¶
If you don’t have a GitLab account you can still create an issue by writing a
mail to incoming+picos-api/picos@incoming.gitlab.com. Unlike issues created
directly on GitLab, issues created by mail are not publicly visible.
Submitting a code change¶
The canoncial way to submit a code change is to
clone your fork and make your application use it instead of your system’s PICOS installation,
optionally create a local topic branch to work with,
modify the source and commit your changes, and lastly
make a pull request on GitLab so that we can test and merge your changes.
If you don’t want to create a GitLab account, we are also happy to receive your
changes via mail as a patch created by git patch.
Implementing your solver¶
If you want to implement support for a new solver, all you have to do is update
solvers.py where applicable, and add a file called
solver_<name>.py in the same directory with your implementation. We recommend
that you read two or three of the existing solver implementations to get an
idea how things are done. If you want to know exactly how PICOS communicates
with your implementation, refer to the solver base class in
solver.py.
Implementing a test case¶
Production and unit test sets are implemented in the files in the
tests folder that start with ptest_ and utest_, respectively.
If you want to add to our test pool, feel free to either extend these files or
create a new set, whatever is appropriate. Make sure that the tests you add are
not too computationally expensive since they are also run as part of our
continuous integration pipeline whenever a commit is pushed to GitLab.
Coding guidelines¶
Cleanup in progress¶
We are aiming to tidy up PICOS’ codebase in the future to make it more robust and easier to maintain and extend. That means that the cost of adding a new feature often is to also refactor around the neighboring features. That being said, you are encouraged to just rewrite a function that you feel does not look so good, even if you initially just planned to add some text to it! :wink:
Test coverage¶
Refactoring means stability in the long run, but can break features in the short term. To prevent this from happening, we’re happy to grow our set of production and unit test cases. Hence, if you are running a local test to see if your changes work, consider adding it as a permanent test case so that your feature is protected from our clumsiness in the future.