.. _contributing:

Contributing to Icarus
======================

We welcome pull requests for bug fixes and new features.

Please ensure that any contributions meet the following criteria:

* clear and easy to understand
* low complexity
* commented
* tested (unit and integration)
* uniform in style and structure
* warning-free

Unit Tests
----------

Unit tests should check that requests sent to Solr are well-formed and fit with expectations.
All permutations of arguments should be tested, including ``None``, empty strings etc.

Unit test module names should begin with ``test_``.

To execute all the unit tests, from the root of the project run the following:

::

 ./bin/run_unit_tests.py

Integration Tests
-----------------

Integration tests run things "for real" and will check the integration of Icarus with a proper Solr instance.

To run the Icarus integration tests you need to have a local Solr instance set up as follows:

* multi-core set-up
* a core named ``icarus_test``
* the schema for ``icarus_test`` needs to be the one included in ``test/resources``
* accessible at http://localhost:8983/solr/#/icarus_test

Integration test module names should begin with ``int_test_``.

To execute all the integration tests, make sure your Solr instance is up and running, then from the root of the project run the following:

::

 ./bin/run_integration_tests.py

Documentation
-------------

All new features must be documented clearly with examples.

This documentation is created using `Sphinx <http://sphinx-doc.org/>`_.

To build and view the documentation locally, run the following from the project root:

::

 ./bin/build_docs.sh
